@object-ui/data-objectstack 17.1.0 → 17.3.0

package/CHANGELOG.md

@@ -1,5 +1,233 @@
 # @object-ui/data-objectstack
 
+## 17.3.0
+
+### Minor Changes
+
+- d22ae31: Track `@objectstack/spec` 17.0.0-rc.2 (objectui#3235, #3208, #3287, #3264).
+
+  The pin moves from `^17.0.0-rc.1` to `^17.0.0-rc.2` across the workspace, and
+  the sibling `@objectstack/*` packages (`client` / `core` / `formula` / `lint`)
+  move with it — they pin `@objectstack/spec` **exactly**, so leaving them behind
+  kept a second copy of the spec in the tree and would have had `@objectstack/lint`
+  validating against rc.1 schemas that still accept keys rc.2 retires.
+
+  Breaking semantics, in FROM → TO form:
+
+  - **`app.homePageId` is retired — an app's landing page is now its first
+    navigation item.** An app that pinned a landing page with `homePageId` will
+    open on the first reachable navigation entry (by `order`) instead; the root
+    landing still follows `isDefault`. To restore a specific landing page, reorder
+    `navigation` so the intended entry comes first. Stored metadata is migrated by
+    `os migrate meta --from 16`. The key is a hard error now, not a stripped one:
+    the spec ships a tombstone that names the migration.
+    Upstream retired it because of its SHAPE, not its usage — it was an ID
+    cross-reference with no referential integrity, so a `homePageId` that pointed
+    at nothing silently fell back to the first navigation item anyway
+    (objectstack#4667, premise corrected in #4709). If the capability returns, it
+    returns as a flag on the navigation item itself, which cannot dangle.
+  - **`@object-ui/types`' `HttpMethod` now resolves to the spec's
+    `HttpMethodType`.** Shape is verbatim identical — the same 5-value UI subset —
+    and `@object-ui/types` still exports it as `HttpMethod`, so no consumer
+    changes. The spec renamed its `./ui` export because `HttpMethod` named two
+    different types depending on the import path (`./shared` / `./api` carry a
+    7-value enum including `HEAD` / `OPTIONS`); objectui deliberately keeps the
+    5-value one (objectstack#4691).
+  - **`AppContextSelector.includeAll` / `placement` are gone.** Neither ever did
+    anything in this renderer: context selectors are mandatory-scope, so no "All"
+    row was ever rendered, and `placement: 'topbar'` put nothing in the topbar.
+    Both carried schema defaults, which is why the liveness lint structurally
+    could not flag them — removal was the only channel that reaches an author
+    (framework#4509).
+  - **`NavigationArea.visible` / `order` / `requiredPermissions` are gone.** An
+    area is a layout grouping, not an access boundary. Gating moved down to the
+    navigation ITEM, where `visible` and `requiredPermissions` are unchanged and
+    still enforced. `AppSchemaRenderer`'s area switcher no longer hides an area, so
+    an area whose items are all gated away renders as visible-but-empty rather
+    than disappearing.
+  - **`@object-ui/core` no longer exports `NotificationProtocol`**
+    (`resolveNotificationConfig`, `specNotificationToToast`, `mapSeverityToVariant`,
+    `mapPosition`, `ToastNotification`). It bridged `@objectstack/spec/ui`'s
+    `Notification` / `NotificationConfig`, which objectstack#4610 deleted with no
+    successor. Use `resolveNotificationConfig` from `@object-ui/react`
+    (`NotificationContext`), which owns the live `NotificationSystemConfig` and is
+    what every notification surface already read. Note that the spec's _other_
+    `Notification` — `@objectstack/spec/api` — is the REST inbox row, a different
+    contract, and is deliberately NOT aliased in as a replacement.
+  - **The `email_template` client-side validator now uses
+    `EmailTemplateDefinitionSchema`.** It was pointing at the removed
+    `EmailTemplateSchema`, so authored templates were being checked against the
+    wrong contract: the live one is keyed `name` + `locale` (not `id`) and splits
+    the body into `bodyHtml` / `bodyText` (not `body` + `bodyType`)
+    (objectstack#4616 / #4807).
+
+  Fixes that are not breaking, but were only found because rc.2 stopped being
+  lenient — each had been passing vacuously:
+
+  - **`view` drafts are actually validated now.** The client validator named the
+    aggregated container schema while this admin authors first-class `ViewItem`s,
+    and the container used to strip `viewKind` / `config` in silence — so no view
+    draft ever had one of its own keys checked. It now validates each shape
+    against its own schema (objectui#3312).
+  - **The console's worked examples were wrong**, and being stripped rather than
+    refused: `view.list.object` (the container root already declares it),
+    `job.concurrency` / `job.timeoutMs` (no such keys; the spelling is `timeout`,
+    already in ms), `email_template.from` / `.to` (a template is not a send —
+    the sender override is `fromOverride`, an object), and
+    `datasource.capabilities` / `.healthCheck` (objectstack#4583 removed the
+    former; the latter was never a datasource key). These are the drafts an
+    author — or a model generating metadata — copies.
+  - Action key inventory re-derived: `ActionSchema` gained the package-lock
+    envelope (`_lock*` / `_package*` / `_provenance`), so a packaged action no
+    longer reports them as unknown keys.
+  - The schema-diff panel labels the new `default_mismatch` finding.
+  - Test fixtures pinning the retired `managedBy: 'system'` bucket now use
+    `engine-owned`. Protocol 17 split that value (objectstack#3355), so it
+    resolved to the default-writable fallback and a batch of "stays locked"
+    assertions had quietly stopped asserting anything.
+
+### Patch Changes
+
+- Updated dependencies [18cd432]
+- Updated dependencies [d915c47]
+- Updated dependencies [5781fb1]
+- Updated dependencies [9e9e9a9]
+- Updated dependencies [23018cc]
+- Updated dependencies [d915c47]
+- Updated dependencies [f44d872]
+- Updated dependencies [509104a]
+- Updated dependencies [a4cff5b]
+- Updated dependencies [f833d3a]
+- Updated dependencies [2a9513d]
+- Updated dependencies [d22ae31]
+  - @object-ui/core@17.3.0
+  - @object-ui/types@17.3.0
+
+## 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,
@@ -76,6 +76,7 @@ function errorCodeIsAnyOf(err, codes) {
 }
 
 // ../core/src/utils/filter-converter.ts
+var import_ui = require("@objectstack/spec/ui");
 var FilterOperatorError = class extends Error {
   constructor(message) {
     super(message);
@@ -933,10 +934,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 +988,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:
@@ -1504,7 +1505,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;
@@ -1533,7 +1534,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];
 }
@@ -1700,7 +1701,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,
@@ -1751,6 +1752,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");
@@ -2127,12 +2153,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 });
   }
@@ -2151,17 +2179,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]
       });
     }
   }
@@ -2181,7 +2217,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);
@@ -2208,7 +2250,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);
@@ -3736,6 +3778,7 @@ function createObjectStackAdapter(config) {
   CloudOperations,
   ConcurrentUpdateError,
   ConnectionError,
+  DataApiValidationError,
   FILTER_OPERATOR_ALIASES,
   IntegrationManager,
   MalformedFilterError,
@@ -3744,7 +3787,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 };