@object-ui/data-objectstack 17.1.0 → 17.2.0

package/CHANGELOG.md

@@ -1,5 +1,130 @@
 # @object-ui/data-objectstack
 
+## 17.2.0
+
+### Minor Changes
+
+- c5ccbd5: Stop declaring 12 `@object-ui/data-objectstack` / `@object-ui/plugin-chatbot` /
+  `@object-ui/plugin-list` symbols under names `@objectstack/spec` owns
+  (objectui#3160, objectstack#4115 batch 6). All three packages leave the ledger.
+
+  **Breaking for importers of `@object-ui/data-objectstack`** — four exported
+  names changed, because the spec exports the same name for a _different_ thing:
+
+  | was                   | now                         | what the spec's same-named export actually is                                            |
+  | :-------------------- | :-------------------------- | :--------------------------------------------------------------------------------------- |
+  | `CacheStats`          | `MetadataCacheStats`        | the platform `ICacheService` counters (`keyCount`, `memoryUsage`)                        |
+  | `MetadataSaveOptions` | `MetadataClientSaveOptions` | options for writing a metadata item to a **file** (`format`, `path`, `indent`, `atomic`) |
+  | `SecurityPolicy`      | `SecurityManagerPolicy`     | the package supply-chain policy (`autoScan`, licences, code signing, sandbox)            |
+  | `ValidationError`     | `DataApiValidationError`    | a plain `{ field, message, code? }` entry in a validation report                         |
+
+  Each pair is disjoint or nearly so — `MetadataSaveOptions` and `SecurityPolicy`
+  share not one key with the spec type whose name they wore — so none of them was
+  a dialect to reconcile; they were four unrelated concepts squatting on spec
+  names. `DataApiValidationError` follows the `<what was validated>Validation<Error|Result>`
+  convention registered on objectstack#4115 (`@object-ui/core` took
+  `SchemaNodeValidationError` in batch 4). Its **runtime** `name` deliberately
+  stays `'ValidationError'`: `normaliseClientError` and `@object-ui/react`'s
+  error-message helper both sniff `err.name`, so that string is a wire contract,
+  not a symbol.
+
+  **Breaking for importers of `@object-ui/plugin-chatbot`** — `PendingActionRow`
+  and `PendingActionStatus` are now re-exported from `@objectstack/spec/contracts`
+  instead of hand-transcribed, which narrows them. The copies had drifted three
+  ways, and each drift had **disabled a compile-time check** rather than merely
+  differed from one:
+
+  - `status: PendingActionStatus | string` — a union with `string` absorbs the
+    literals, so that annotation carried no information at all;
+  - `[key: string]: unknown` — the objectstack#4075 mechanism: an index signature
+    makes every structural comparison against the spec answer "identical", however
+    far the copy has drifted;
+  - `created_at` / `updated_at`, which the service contract does not carry and no
+    consumer in this repo reads.
+
+  **Breaking for importers of `@object-ui/plugin-list`** — `ViewTab` is derived from the spec's `ViewTabSchema`
+  — from its **input** side, because `pinned` / `isDefault` / `visible` carry
+  `.default()`s and this component is handed authored metadata, not parsed output.
+  That removes a renderer-side tolerance the copy carried: `visible` accepted
+  `string | boolean` and the tab bar compared it against the literal `'false'`, a
+  spelling no producer emits. `label` also stops being required (the spec makes it
+  optional; `name` is the identifier) and `filter` stops being `any`.
+
+  `ListView` and `UserFilters` keep their names as declared dialects: both are the
+  React **renderers** of the spec types whose names they share, and each takes that
+  spec type as a prop (`ListViewProps.schema`, `UserFiltersProps.config`) rather
+  than restating its shape. `Tool` and `MessageContent` in `plugin-chatbot` are
+  vendored Vercel AI Elements / Shadcn primitives — upstream's component API, not
+  objectui's authored surface — so the guard now skips that directory the same way
+  it already skips `components/src/ui/`, with a test that fails if any file there
+  stops carrying its vendor banner.
+
+  Scored `minor`, not `major`, per this repo's fixed-group rule — objectui's major
+  tracks `@objectstack`, so breaking changes of our own ship as minor with the
+  semantics spelled out above (see AGENTS.md §版本号策略). A `major` here would carry
+  all 39 packages of the fixed group to `18.0.0` and off objectstack's 17.x line.
+
+- d3584c6: Bring the whole `@objectstack` family to `17.0.0-rc.1`, so the dependency graph resolves a
+  single copy of `@objectstack/spec`.
+
+  #3178 bumped **only** `@objectstack/spec` to `17.0.0-rc.1`. The rest of the family —
+  `client`, `core`, `formula`, `lint` (and `sdui-parser`, reached through `lint`) — stayed on
+  `17.0.0-rc.0`, and each of them depends on spec at an **exact** version rather than a
+  caret:
+
+  ```
+  @objectstack/client@17.0.0-rc.0  -> spec "17.0.0-rc.0"
+  @objectstack/core@17.0.0-rc.0    -> spec "17.0.0-rc.0"
+  @objectstack/formula@17.0.0-rc.0 -> spec "17.0.0-rc.0"
+  @objectstack/lint@17.0.0-rc.0    -> spec "17.0.0-rc.0"
+  ```
+
+  So `main` carried **two** spec copies: objectui's own code read `17.0.0-rc.1` while every
+  `@objectstack/*` package read `17.0.0-rc.0` from its own nested `node_modules`. That breaks
+  the single-contract invariant this repo's guards are built on, and it breaks them
+  _silently_ — the affected checks depend on identity, not on version strings:
+
+  - `spec-subschema-parity.test.ts` distinguishes a genuine re-export from a fork by
+    **reference identity** of the zod schema object. Two spec copies make every schema a
+    distinct object, so a real re-export starts reading as a fork (or a fork slips through,
+    depending on which copy each side resolved).
+  - `scripts/check-spec-symbol-derivation.mjs` and `spec-symbol-parity.test.ts` use
+    `createRequire` to resolve spec's `.d.ts` and run it through the TS checker. With two
+    copies installed, _which_ declaration file the checker sees is a function of resolution
+    order rather than of intent.
+
+  The declared ranges were already `^17.0.0-rc.0`, which technically admits rc.1 — the pin
+  lived in the lockfile. Raising the remaining ranges to `^17.0.0-rc.1` makes the floor
+  explicit and forbids a future install from silently sliding back onto a family member that
+  drags rc.0 along with it. The rc.1 family members pin spec at `17.0.0-rc.1` exactly, so the
+  graph now converges on one copy by construction, not by luck.
+
+  No product behaviour changes here. `check:spec-symbols` reconciliation was already
+  completed by #3178 and stays green under the unified graph; this changeset is `minor`
+  per the repo's fixed-group version policy.
+
+### Patch Changes
+
+- Updated dependencies [4ae0ac4]
+- Updated dependencies [696e3c1]
+- Updated dependencies [bca45cc]
+- Updated dependencies [4bf612c]
+- Updated dependencies [335041c]
+- Updated dependencies [b414983]
+- Updated dependencies [256f8cc]
+- Updated dependencies [d9668a7]
+- Updated dependencies [cb82705]
+- Updated dependencies [f572849]
+- Updated dependencies [d3584c6]
+- Updated dependencies [a8ad6c0]
+- Updated dependencies [444457c]
+- Updated dependencies [850033c]
+- Updated dependencies [022e4c3]
+- Updated dependencies [009e25d]
+- Updated dependencies [726b89c]
+  - @object-ui/types@17.2.0
+  - @object-ui/core@17.2.0
+
 ## 17.1.0
 
 ### Minor Changes

package/README.md

@@ -179,7 +179,12 @@ import {
   BulkOperationError,      // Bulk operation failures with partial results
   ConnectionError,         // Network/connection errors (503/504)
   AuthenticationError,     // Authentication failures (401/403)
-  ValidationError,         // Data validation errors (400)
+  DataApiValidationError,  // Data validation errors (400). Its runtime `name` is
+                           // still 'ValidationError' — that string is the wire
+                           // discriminator shared with @objectstack/client. The
+                           // SYMBOL is prefixed because @objectstack/spec/kernel
+                           // owns `ValidationError` for a { field, message, code? }
+                           // record (objectui#3160).
 } from '@object-ui/data-objectstack';
 ```
 

package/dist/index.cjs

@@ -29,6 +29,7 @@ __export(index_exports, {
   CloudOperations: () => CloudOperations,
   ConcurrentUpdateError: () => ConcurrentUpdateError,
   ConnectionError: () => ConnectionError,
+  DataApiValidationError: () => DataApiValidationError,
   FILTER_OPERATOR_ALIASES: () => FILTER_OPERATOR_ALIASES,
   IntegrationManager: () => IntegrationManager,
   MalformedFilterError: () => MalformedFilterError,
@@ -37,7 +38,6 @@ __export(index_exports, {
   ObjectStackAdapter: () => ObjectStackAdapter,
   ObjectStackError: () => ObjectStackError,
   SecurityManager: () => SecurityManager,
-  ValidationError: () => ValidationError,
   calculateAutoLayout: () => calculateAutoLayout,
   classifyAnalyticsFailure: () => classifyAnalyticsFailure,
   clearSharedDiscoveryCache: () => clearSharedDiscoveryCache,
@@ -933,10 +933,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
@@ -987,7 +987,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:
@@ -1700,7 +1700,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,
@@ -3736,6 +3736,7 @@ function createObjectStackAdapter(config) {
   CloudOperations,
   ConcurrentUpdateError,
   ConnectionError,
+  DataApiValidationError,
   FILTER_OPERATOR_ALIASES,
   IntegrationManager,
   MalformedFilterError,
@@ -3744,7 +3745,6 @@ function createObjectStackAdapter(config) {
   ObjectStackAdapter,
   ObjectStackError,
   SecurityManager,
-  ValidationError,
   calculateAutoLayout,
   classifyAnalyticsFailure,
   clearSharedDiscoveryCache,

package/dist/index.d.cts

@@ -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.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

@@ -880,10 +880,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 +934,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:
@@ -1647,7 +1647,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,
@@ -3682,6 +3682,7 @@ export {
   CloudOperations,
   ConcurrentUpdateError,
   ConnectionError,
+  DataApiValidationError,
   FILTER_OPERATOR_ALIASES,
   IntegrationManager,
   MalformedFilterError,
@@ -3690,7 +3691,6 @@ export {
   ObjectStackAdapter,
   ObjectStackError,
   SecurityManager,
-  ValidationError,
   calculateAutoLayout,
   classifyAnalyticsFailure,
   clearSharedDiscoveryCache,