@object-ui/data-objectstack 17.1.0 → 17.3.0

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import { ObjectStackClient } from '@objectstack/client';
+import { DroppedFieldsEvent } from '@objectstack/spec/data';
+export { DroppedFieldsEvent } from '@objectstack/spec/data';
 import { DataSource, QueryParams, QueryResult, GlobalSearchResult, DataSourceMutationEvent, BatchTransactionOperation, ImportRequestOptions, ImportRecordsResult, CreateImportJobResult, ImportJobProgressInfo, ImportJobResultsInfo, ListImportJobsOptions, ImportJobSummaryInfo, ImportJobUndoResult, ExportDownloadRequest, FileUploadResult } from '@object-ui/types';
 export { FileUploadResult } from '@object-ui/types';
 
@@ -95,16 +97,28 @@ declare class AuthenticationError extends ObjectStackError {
     constructor(message?: string, details?: Record<string, unknown>, statusCode?: number);
 }
 /**
- * Error thrown when data validation fails
+ * Error thrown when the ObjectStack data API rejects a write as invalid.
+ *
+ * NOT the spec's `ValidationError` (`@objectstack/spec/kernel`), whose name this
+ * class wore until objectui#3160 (objectstack#4115 ledger batch 6). That one is
+ * a plain DATA SHAPE — `{ field, message, code? }`, one entry in a plugin
+ * manifest's validation report — and `@object-ui/types` re-exports it under that
+ * name. This is a runtime `Error` subclass carrying an HTTP status plus a list
+ * of such entries, so the two are not even the same KIND of thing.
+ *
+ * The name follows the convention registered on objectstack#4115 for this
+ * family — `<what was validated>Validation<Error|Result>`. `@object-ui/core`
+ * took `SchemaNodeValidationError` for its SDUI-tree walk; this one belongs to
+ * the data API.
  */
-declare class ValidationError extends ObjectStackError {
+declare class DataApiValidationError extends ObjectStackError {
     field?: string | undefined;
     validationErrors?: Array<{
         field: string;
         message: string;
     }> | undefined;
     /**
-     * Create a new ValidationError
+     * Create a new DataApiValidationError
      *
      * @param message - Human-readable error message
      * @param field - The field that failed validation (optional)
@@ -148,9 +162,18 @@ declare function isErrorType<T extends ObjectStackError>(error: unknown, errorCl
  * LICENSE file in the root directory of this source tree.
  */
 /**
- * Cache statistics for monitoring
+ * Statistics reported by {@link MetadataCache.getStats} for monitoring.
+ *
+ * NOT the spec's `CacheStats` (`@objectstack/spec/contracts`), whose name this
+ * interface wore until objectui#3160 (objectstack#4115 ledger batch 6). That one
+ * describes the platform's `ICacheService` — a server-side KV cache measured by
+ * `keyCount` and `memoryUsage`. This one describes the browser-side LRU in front
+ * of `/api/v1/meta/*`: it is bounded (`size`/`maxSize`), it evicts, it coalesces
+ * concurrent fetches onto one in-flight promise, and it reports a `hitRate`.
+ * Neither type has a key the other has, so this is a name collision, not a
+ * dialect — deriving would have replaced every field.
  */
-interface CacheStats {
+interface MetadataCacheStats {
     size: number;
     maxSize: number;
     hits: number;
@@ -563,7 +586,21 @@ interface MetadataDraftHeader {
     updatedAt: string | null;
     updatedBy: string | null;
 }
-interface MetadataSaveOptions {
+/**
+ * Options for {@link MetadataClient.save} — a WRITE OVER HTTP to
+ * `/api/v1/meta/:type/:name`.
+ *
+ * NOT the spec's `MetadataSaveOptions` (`@objectstack/spec/system` and
+ * `/kernel`), whose name this interface wore until objectui#3160
+ * (objectstack#4115 ledger batch 6). Both spec copies describe writing a
+ * metadata item to a FILE — `format: json|yaml|ts`, `path`, `indent`,
+ * `prettify`, `sortKeys`, `backup`, `atomic`, `loader`. Not one of those keys
+ * exists here, and not one of these exists there: this is the REST client's
+ * request envelope — optimistic concurrency (`ifMatch` → `If-Match`), actor
+ * attribution, the destructive-change override, the ADR-0033 draft/publish
+ * mode, and the owning package. Same words, different layer.
+ */
+interface MetadataClientSaveOptions {
     /**
      * Optimistic concurrency token (the `checksum` returned by the last
      * read). When present, sent as the `If-Match` header so concurrent
@@ -608,7 +645,7 @@ interface MetadataGetOptions {
      */
     packageId?: string;
 }
-interface MetadataDeleteOptions extends MetadataSaveOptions {
+interface MetadataDeleteOptions extends MetadataClientSaveOptions {
     /**
      * Target state. `'draft'` discards the pending draft (keeps the
      * published overlay intact). Omit to reset the active overlay back
@@ -847,7 +884,7 @@ declare class MetadataClient {
      * envelopes; we send bare for consistency. Pass `mode: 'draft'` to
      * stage the change without publishing (Studio's "Save" button).
      */
-    save<T = unknown>(type: string, name: string, item: unknown, options?: MetadataSaveOptions): Promise<T>;
+    save<T = unknown>(type: string, name: string, item: unknown, options?: MetadataClientSaveOptions): Promise<T>;
     /**
      * Publish a single pending draft BY REFERENCE — promotes the draft row for
      * `(type, name)` into the active overlay and drops the draft. Works for ANY
@@ -957,7 +994,20 @@ declare class MetadataClient {
  * Security module integration for @objectstack/spec v3.0.0
  * Provides advanced security policies: CSP config, audit logging, data masking.
  */
-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.
+ */
+interface SecurityManagerPolicy {
     /** Content Security Policy configuration */
     csp?: CSPConfig;
     /** Audit logging configuration */
@@ -1031,7 +1081,7 @@ interface AuditLogEntry {
 declare class SecurityManager {
     private policy;
     private auditLog;
-    constructor(policy?: SecurityPolicy);
+    constructor(policy?: SecurityManagerPolicy);
     /**
      * Generate a CSP header string from the configuration.
      */
@@ -1055,11 +1105,11 @@ declare class SecurityManager {
     /**
      * Update the security policy.
      */
-    updatePolicy(policy: Partial<SecurityPolicy>): void;
+    updatePolicy(policy: Partial<SecurityManagerPolicy>): void;
     /**
      * Get current security policy.
      */
-    getPolicy(): SecurityPolicy;
+    getPolicy(): SecurityManagerPolicy;
 }
 
 /**
@@ -1379,7 +1429,7 @@ declare function isConcurrentUpdateError(error: unknown): error is ConcurrentUpd
  *
  * Two shapes are recognised:
  *   - `409` + `CONCURRENT_UPDATE` → {@link ConcurrentUpdateError};
- *   - `400` + `VALIDATION_FAILED` → {@link ValidationError}, carrying the
+ *   - `400` + `VALIDATION_FAILED` → {@link DataApiValidationError}, carrying the
  *     server's per-field entries so a form can mark the offending inputs
  *     instead of showing one undirected toast.
  */
@@ -1414,19 +1464,7 @@ type ConnectionStateListener = (event: ConnectionStateEvent) => void;
  * Event listener type for batch operation progress
  */
 type BatchProgressListener = (event: BatchProgressEvent) => void;
-/**
- * One server-reported write-strip: caller-supplied fields the backend LEGALLY
- * removed from a write before persisting (a non-system caller cannot seed a
- * `readonly` field, a `readonlyWhen` predicate locked it, etc.). Mirrors the
- * framework `DroppedFieldsEvent` (spec `DroppedFieldsEventSchema`) structurally
- * so we don't pin a client type version — `reason` is kept as a widened string
- * for forward-compatibility with reasons added server-side.
- */
-interface DroppedFieldsEvent {
-    object: string;
-    fields: string[];
-    reason: string;
-}
+
 /**
  * Emitted after a create/update whose response carried `droppedFields`
  * (framework #3431/#3455). The write SUCCEEDED — this is a warning that some
@@ -2085,7 +2123,7 @@ declare class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     /**
      * Get cache statistics for monitoring performance.
      */
-    getCacheStats(): CacheStats;
+    getCacheStats(): MetadataCacheStats;
     /**
      * Invalidate metadata cache entries.
      *
@@ -2173,4 +2211,4 @@ declare function createObjectStackAdapter<T = unknown>(config: {
     reconnectDelay?: number;
 }): DataSource<T>;
 
-export { AnalyticsNotInstalledError, AnalyticsQueryRejectedError, type AuditEventType, type AuditLogConfig, type AuditLogEntry, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, type CSPConfig, type CacheStats, type CloudDeploymentConfig, type CloudHostingConfig, type CloudMarketplaceEntry, CloudOperations, ConcurrentUpdateError, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, type ContractValidationError, type ContractValidationResult, type DataMaskingConfig, type DataMaskingRule, type DroppedFieldsEvent, type EmailIntegrationConfig, FILTER_OPERATOR_ALIASES, type IntegrationConfig, IntegrationManager, type IntegrationProvider, type IntegrationTrigger, MalformedFilterError, type MetadataAuditEntry, type MetadataAuditResponse, MetadataClient, type MetadataClientConfig, type MetadataDeleteOptions, type MetadataDiagnostics, type MetadataDiagnosticsEntry, type MetadataDiagnosticsOptions, type MetadataDiagnosticsSummary, type MetadataDraftHeader, type MetadataError, type MetadataGetOptions, type MetadataHistoryOptions, type MetadataLayered, type MetadataListOptions, MetadataNotFoundError, type MetadataReference, type MetadataSaveOptions, type MetadataValidationIssue, ObjectStackAdapter, ObjectStackError, type ObjectStackUserStateAdapterOptions, type PluginAPIContract, type PluginContract, type PluginExport, SecurityManager, type SecurityPolicy, type SlackIntegrationConfig, type StudioCanvasConfig, type StudioColorPalette, type StudioPropertyEditor, type StudioShadowPreset, type StudioThemeBuilderConfig, type StudioTypographyPreset, type UserDataAdapter, ValidationError, type WebhookIntegrationConfig, type WriteWarningEvent, type WriteWarningListener, calculateAutoLayout, classifyAnalyticsFailure, clearSharedDiscoveryCache, createDefaultCanvasConfig, createErrorFromResponse, createObjectStackAdapter, createObjectStackUserStateAdapter, generateContractManifest, getSharedDiscovery, is404Error, isAnalyticsNotInstalledError, isConcurrentUpdateError, isErrorType, isMalformedFilterError, isObjectStackError, normaliseClientError, readTransactionalBatchCapability, serializeOrderBy, snapToGrid, validatePluginContract };
+export { AnalyticsNotInstalledError, AnalyticsQueryRejectedError, type AuditEventType, type AuditLogConfig, type AuditLogEntry, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, type CSPConfig, type CloudDeploymentConfig, type CloudHostingConfig, type CloudMarketplaceEntry, CloudOperations, ConcurrentUpdateError, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, type ContractValidationError, type ContractValidationResult, DataApiValidationError, type DataMaskingConfig, type DataMaskingRule, type EmailIntegrationConfig, FILTER_OPERATOR_ALIASES, type IntegrationConfig, IntegrationManager, type IntegrationProvider, type IntegrationTrigger, MalformedFilterError, type MetadataAuditEntry, type MetadataAuditResponse, type MetadataCacheStats, MetadataClient, type MetadataClientConfig, type MetadataClientSaveOptions, type MetadataDeleteOptions, type MetadataDiagnostics, type MetadataDiagnosticsEntry, type MetadataDiagnosticsOptions, type MetadataDiagnosticsSummary, type MetadataDraftHeader, type MetadataError, type MetadataGetOptions, type MetadataHistoryOptions, type MetadataLayered, type MetadataListOptions, MetadataNotFoundError, type MetadataReference, type MetadataValidationIssue, ObjectStackAdapter, ObjectStackError, type ObjectStackUserStateAdapterOptions, type PluginAPIContract, type PluginContract, type PluginExport, SecurityManager, type SecurityManagerPolicy, type SlackIntegrationConfig, type StudioCanvasConfig, type StudioColorPalette, type StudioPropertyEditor, type StudioShadowPreset, type StudioThemeBuilderConfig, type StudioTypographyPreset, type UserDataAdapter, type WebhookIntegrationConfig, type WriteWarningEvent, type WriteWarningListener, calculateAutoLayout, classifyAnalyticsFailure, clearSharedDiscoveryCache, createDefaultCanvasConfig, createErrorFromResponse, createObjectStackAdapter, createObjectStackUserStateAdapter, generateContractManifest, getSharedDiscovery, is404Error, isAnalyticsNotInstalledError, isConcurrentUpdateError, isErrorType, isMalformedFilterError, isObjectStackError, normaliseClientError, readTransactionalBatchCapability, serializeOrderBy, snapToGrid, validatePluginContract };

package/dist/index.js

@@ -23,6 +23,7 @@ function errorCodeIsAnyOf(err, codes) {
 }
 
 // ../core/src/utils/filter-converter.ts
+import { normalizeFilterOperator } from "@objectstack/spec/ui";
 var FilterOperatorError = class extends Error {
   constructor(message) {
     super(message);
@@ -880,10 +881,10 @@ var AuthenticationError = class extends ObjectStackError {
     this.name = "AuthenticationError";
   }
 };
-var ValidationError = class extends ObjectStackError {
+var DataApiValidationError = class extends ObjectStackError {
   /**
-   * Create a new ValidationError
-   * 
+   * Create a new DataApiValidationError
+   *
    * @param message - Human-readable error message
    * @param field - The field that failed validation (optional)
    * @param validationErrors - Array of validation error details
@@ -934,7 +935,7 @@ function createErrorFromResponse(response, context) {
       }
       return new ObjectStackError(message, "NOT_FOUND", 404, details);
     case 400:
-      return new ValidationError(message, void 0, response?.data?.errors, details);
+      return new DataApiValidationError(message, void 0, response?.data?.errors, details);
     case 503:
       return new ConnectionError(message, response?.config?.url, details, 503);
     case 504:
@@ -1451,7 +1452,7 @@ var FILTER_OPERATOR_ALIASES = {
   before: "<",
   after: ">"
 };
-function normalizeFilterOperator(op) {
+function normalizeFilterOperator2(op) {
   if (typeof op !== "string") return null;
   const lower = op.toLowerCase();
   return FILTER_OPERATOR_ALIASES[lower] ?? FILTER_OPERATOR_ALIASES[op] ?? op;
@@ -1480,7 +1481,7 @@ function objectFilterEntryToAST(entry) {
   if (!entry || typeof entry !== "object") return null;
   const field = entry.field;
   const rawOp = entry.operator ?? entry.op ?? "=";
-  const op = normalizeFilterOperator(rawOp);
+  const op = normalizeFilterOperator2(rawOp);
   if (!field || !op) return null;
   return [String(field), op, entry.value];
 }
@@ -1647,7 +1648,7 @@ function normaliseClientError(error) {
       const message = typeof rec.message === "string" && rec.message.trim() ? rec.message : typeof rec.code === "string" ? rec.code : "";
       return { field, message };
     }).filter((x) => x !== null);
-    return new ValidationError(
+    return new DataApiValidationError(
       typeof e.message === "string" ? e.message : "Validation failed",
       validationErrors[0]?.field,
       validationErrors,
@@ -1698,6 +1699,31 @@ function stableStringify(value) {
   const keys = Object.keys(obj).sort();
   return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(",")}}`;
 }
+function sameWireValue(a, b) {
+  if (a === b) return true;
+  const aEmpty = a === null || a === void 0;
+  const bEmpty = b === null || b === void 0;
+  if (aEmpty || bEmpty) return aEmpty && bEmpty;
+  return stableStringify(a) === stableStringify(b);
+}
+function withoutNoOpDrops(droppedFields, sent, stored) {
+  if (!sent || !stored || typeof sent !== "object" || typeof stored !== "object") {
+    return droppedFields;
+  }
+  const out = [];
+  for (const e of droppedFields) {
+    const kept = e.fields.filter((f) => {
+      if (!Object.prototype.hasOwnProperty.call(sent, f)) return true;
+      if (!Object.prototype.hasOwnProperty.call(stored, f)) return true;
+      return !sameWireValue(
+        sent[f],
+        stored[f]
+      );
+    });
+    if (kept.length > 0) out.push({ ...e, fields: kept });
+  }
+  return out;
+}
 var ObjectStackAdapter = class {
   constructor(config) {
     __publicField(this, "client");
@@ -2074,12 +2100,14 @@ var ObjectStackAdapter = class {
    * whose response type predates `droppedFields`: the field is read structurally
    * and validated, so an older client (or a backend that never drops) is a no-op.
    */
-  notifyDroppedFields(operation, resource, result, id) {
+  notifyDroppedFields(operation, resource, result, id, sent) {
     const dropped = result?.droppedFields;
     if (!Array.isArray(dropped) || dropped.length === 0) return;
-    const droppedFields = dropped.filter(
+    const valid = dropped.filter(
       (e) => !!e && typeof e === "object" && Array.isArray(e.fields) && e.fields.length > 0
     );
+    const stored = result?.record;
+    const droppedFields = withoutNoOpDrops(valid, sent, stored);
     if (droppedFields.length === 0) return;
     this.emitWriteWarning({ operation, resource, ...id !== void 0 ? { id } : {}, droppedFields });
   }
@@ -2098,17 +2126,25 @@ var ObjectStackAdapter = class {
   notifyBatchDroppedFields(operations, payload) {
     const dropped = payload?.droppedFields;
     if (!Array.isArray(dropped) || dropped.length === 0) return;
+    const results = payload?.results;
     for (const entry of dropped) {
       if (!entry || typeof entry !== "object") continue;
       const e = entry;
       if (!Array.isArray(e.fields) || e.fields.length === 0) continue;
       const op = typeof e.index === "number" ? operations[e.index] : void 0;
+      const stored = typeof e.index === "number" && Array.isArray(results) ? results[e.index] : void 0;
+      const [live] = withoutNoOpDrops(
+        [{ object: e.object, fields: e.fields, reason: e.reason }],
+        op?.data,
+        stored
+      );
+      if (!live) continue;
       const operation = (op?.action ?? "create") === "create" ? "create" : "update";
       this.emitWriteWarning({
         operation,
         resource: e.object ?? op?.object ?? "",
         ...op?.id !== void 0 && op?.id !== null ? { id: op.id } : {},
-        droppedFields: [{ object: e.object, fields: e.fields, reason: e.reason }]
+        droppedFields: [live]
       });
     }
   }
@@ -2128,7 +2164,13 @@ var ObjectStackAdapter = class {
     try {
       const result = await this.client.data.create(resource, data);
       this.emitMutation({ type: "create", resource, record: { ...result.record } });
-      this.notifyDroppedFields("create", resource, result, result.record?.id);
+      this.notifyDroppedFields(
+        "create",
+        resource,
+        result,
+        result.record?.id,
+        data
+      );
       return result.record;
     } catch (err) {
       throw normaliseClientError(err);
@@ -2155,7 +2197,7 @@ var ObjectStackAdapter = class {
         opts?.ifMatch ? { ifMatch: opts.ifMatch } : void 0
       );
       this.emitMutation({ type: "update", resource, id, record: { ...result.record } });
-      this.notifyDroppedFields("update", resource, result, id);
+      this.notifyDroppedFields("update", resource, result, id, data);
       return result.record;
     } catch (err) {
       throw normaliseClientError(err);
@@ -3682,6 +3724,7 @@ export {
   CloudOperations,
   ConcurrentUpdateError,
   ConnectionError,
+  DataApiValidationError,
   FILTER_OPERATOR_ALIASES,
   IntegrationManager,
   MalformedFilterError,
@@ -3690,7 +3733,6 @@ export {
   ObjectStackAdapter,
   ObjectStackError,
   SecurityManager,
-  ValidationError,
   calculateAutoLayout,
   classifyAnalyticsFailure,
   clearSharedDiscoveryCache,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/data-objectstack",
-  "version": "17.1.0",
+  "version": "17.3.0",
   "description": "ObjectStack Data Adapter for Object UI",
   "license": "MIT",
   "type": "module",
@@ -22,12 +22,12 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@objectstack/client": "^17.0.0-rc.0",
-    "@object-ui/core": "17.1.0",
-    "@object-ui/types": "17.1.0"
+    "@objectstack/client": "^17.0.0-rc.2",
+    "@objectstack/spec": "^17.0.0-rc.2",
+    "@object-ui/core": "17.3.0",
+    "@object-ui/types": "17.3.0"
   },
   "devDependencies": {
-    "@objectstack/spec": "^17.0.0-rc.0",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"

package/src/cache/MetadataCache.ts

@@ -17,9 +17,18 @@ interface CachedSchema {
 }
 
 /**
- * Cache statistics for monitoring
+ * Statistics reported by {@link MetadataCache.getStats} for monitoring.
+ *
+ * NOT the spec's `CacheStats` (`@objectstack/spec/contracts`), whose name this
+ * interface wore until objectui#3160 (objectstack#4115 ledger batch 6). That one
+ * describes the platform's `ICacheService` — a server-side KV cache measured by
+ * `keyCount` and `memoryUsage`. This one describes the browser-side LRU in front
+ * of `/api/v1/meta/*`: it is bounded (`size`/`maxSize`), it evicts, it coalesces
+ * concurrent fetches onto one in-flight promise, and it reports a `hitRate`.
+ * Neither type has a key the other has, so this is a name collision, not a
+ * dialect — deriving would have replaced every field.
  */
-export interface CacheStats {
+export interface MetadataCacheStats {
   size: number;
   maxSize: number;
   hits: number;
@@ -218,7 +227,7 @@ export class MetadataCache {
    * 
    * @returns Cache statistics including hit rate
    */
-  getStats(): CacheStats {
+  getStats(): MetadataCacheStats {
     const total = this.stats.hits + this.stats.misses;
     const hitRate = total > 0 ? this.stats.hits / total : 0;
 

package/src/errors.test.ts

@@ -13,7 +13,7 @@ import {
   BulkOperationError,
   ConnectionError,
   AuthenticationError,
-  ValidationError,
+  DataApiValidationError,
   createErrorFromResponse,
   isObjectStackError,
   isErrorType,
@@ -189,20 +189,20 @@ describe('Error Classes', () => {
     });
   });
 
-  describe('ValidationError', () => {
+  describe('DataApiValidationError', () => {
     it('should create validation error', () => {
-      const error = new ValidationError('Invalid input');
+      const error = new DataApiValidationError('Invalid input');
 
       expect(error.message).toBe('Invalid input');
       expect(error.code).toBe('VALIDATION_ERROR');
       expect(error.statusCode).toBe(400);
       expect(error.name).toBe('ValidationError');
       expect(error).toBeInstanceOf(ObjectStackError);
-      expect(error).toBeInstanceOf(ValidationError);
+      expect(error).toBeInstanceOf(DataApiValidationError);
     });
 
     it('should include field information', () => {
-      const error = new ValidationError('Email is invalid', 'email');
+      const error = new DataApiValidationError('Email is invalid', 'email');
 
       expect(error.field).toBe('email');
       expect(error.details).toHaveProperty('field', 'email');
@@ -214,7 +214,7 @@ describe('Error Classes', () => {
         { field: 'age', message: 'Must be a positive number' },
       ];
       
-      const error = new ValidationError(
+      const error = new DataApiValidationError(
         'Validation failed',
         undefined,
         validationErrors
@@ -225,7 +225,7 @@ describe('Error Classes', () => {
     });
 
     it('should return empty array when no validation errors', () => {
-      const error = new ValidationError('Validation failed');
+      const error = new DataApiValidationError('Validation failed');
 
       expect(error.getValidationErrors()).toEqual([]);
     });
@@ -286,7 +286,7 @@ describe('Error Helpers', () => {
       expect(error.code).toBe('NOT_FOUND');
     });
 
-    it('should create ValidationError for 400 status', () => {
+    it('should create DataApiValidationError for 400 status', () => {
       const response = {
         status: 400,
         message: 'Bad request',
@@ -299,9 +299,9 @@ describe('Error Helpers', () => {
 
       const error = createErrorFromResponse(response);
 
-      expect(error).toBeInstanceOf(ValidationError);
+      expect(error).toBeInstanceOf(DataApiValidationError);
       expect(error.statusCode).toBe(400);
-      expect((error as ValidationError).validationErrors).toEqual([
+      expect((error as DataApiValidationError).validationErrors).toEqual([
         { field: 'email', message: 'Invalid email' },
       ]);
     });
@@ -379,7 +379,7 @@ describe('Error Helpers', () => {
       const bulkError = new BulkOperationError('create', 0, 1, []);
       const connError = new ConnectionError('timeout');
       const authError = new AuthenticationError();
-      const validError = new ValidationError('invalid');
+      const validError = new DataApiValidationError('invalid');
 
       expect(isObjectStackError(metadataError)).toBe(true);
       expect(isObjectStackError(bulkError)).toBe(true);
@@ -409,7 +409,7 @@ describe('Error Helpers', () => {
 
     it('should return false for non-matching error type', () => {
       const error = new MetadataNotFoundError('users');
-      expect(isErrorType(error, ValidationError)).toBe(false);
+      expect(isErrorType(error, DataApiValidationError)).toBe(false);
     });
 
     it('should return true for base class check', () => {

package/src/errors.ts

@@ -159,12 +159,24 @@ export class AuthenticationError extends ObjectStackError {
 }
 
 /**
- * Error thrown when data validation fails
+ * Error thrown when the ObjectStack data API rejects a write as invalid.
+ *
+ * NOT the spec's `ValidationError` (`@objectstack/spec/kernel`), whose name this
+ * class wore until objectui#3160 (objectstack#4115 ledger batch 6). That one is
+ * a plain DATA SHAPE — `{ field, message, code? }`, one entry in a plugin
+ * manifest's validation report — and `@object-ui/types` re-exports it under that
+ * name. This is a runtime `Error` subclass carrying an HTTP status plus a list
+ * of such entries, so the two are not even the same KIND of thing.
+ *
+ * The name follows the convention registered on objectstack#4115 for this
+ * family — `<what was validated>Validation<Error|Result>`. `@object-ui/core`
+ * took `SchemaNodeValidationError` for its SDUI-tree walk; this one belongs to
+ * the data API.
  */
-export class ValidationError extends ObjectStackError {
+export class DataApiValidationError extends ObjectStackError {
   /**
-   * Create a new ValidationError
-   * 
+   * Create a new DataApiValidationError
+   *
    * @param message - Human-readable error message
    * @param field - The field that failed validation (optional)
    * @param validationErrors - Array of validation error details
@@ -186,6 +198,12 @@ export class ValidationError extends ObjectStackError {
         ...details,
       }
     );
+    // The RUNTIME name stays `'ValidationError'` on purpose — it is the wire
+    // discriminator this adapter shares with `@objectstack/client` and with
+    // consumers that sniff `err.name` rather than `instanceof`
+    // (`normaliseClientError` here, `@object-ui/react`'s `error-message`).
+    // Renaming the TypeScript symbol is a source-level rename; renaming this
+    // string would be a behaviour change nobody asked for.
     this.name = 'ValidationError';
   }
 
@@ -232,7 +250,7 @@ export function createErrorFromResponse(response: Record<string, unknown>, conte
       return new ObjectStackError(message, 'NOT_FOUND', 404, details);
     
     case 400:
-      return new ValidationError(message, undefined, (response?.data as Record<string, unknown>)?.errors as Array<{ field: string; message: string }>, details);
+      return new DataApiValidationError(message, undefined, (response?.data as Record<string, unknown>)?.errors as Array<{ field: string; message: string }>, details);
     
     case 503:
       return new ConnectionError(message, (response?.config as Record<string, unknown>)?.url as string, details, 503);