@object-ui/data-objectstack 16.0.0 → 17.1.0

package/src/index.ts

@@ -9,9 +9,12 @@
 import { ObjectStackClient, type QueryOptions as ObjectStackQueryOptions } from '@objectstack/client';
 import type {
   DataSource,
-  MutationEvent,
+  BatchTransactionOperation,
+  DataSourceMutationEvent,
   QueryParams,
   QueryResult,
+  GlobalSearchResult,
+  GlobalSearchHit,
   FileUploadResult,
   ExportDownloadRequest,
   ImportRequestOptions,
@@ -23,13 +26,20 @@ import type {
   ImportJobUndoResult,
   ListImportJobsOptions,
 } from '@object-ui/types';
-import { convertFiltersToAST, normalizeSchemaReferenceKeys } from '@object-ui/core';
+import { errorCodeIsAnyOf } from '@object-ui/types';
+import {
+  convertFiltersToAST,
+  emulateBatchTransaction,
+  normalizeSchemaReferenceKeys,
+} from '@object-ui/core';
 import { MetadataCache } from './cache/MetadataCache';
+import { MetadataClient } from './metadata-client';
 import {
   ObjectStackError,
   MetadataNotFoundError,
   BulkOperationError,
   ConnectionError,
+  ValidationError,
   createErrorFromResponse,
 } from './errors';
 
@@ -38,8 +48,15 @@ import {
  * (e.g. `lead.view.ts`) to the canonical operator symbols expected by the
  * ObjectStack server's filter AST. Unknown operators fall through unchanged
  * so existing AST-style entries keep working.
+ *
+ * Every VALUE here must be a member of the spec's `VALID_AST_OPERATORS`
+ * (`@objectstack/spec/data`) — that set gates `isFilterAST()`, and a filter it
+ * rejects is not converted, not validated, and then silently DROPPED by
+ * driver-sql (objectstack#3948). Pinned by `filter-operator-ast-parity.test.ts`.
+ *
+ * Exported for that test. @internal
  */
-const FILTER_OPERATOR_ALIASES: Record<string, string> = {
+export const FILTER_OPERATOR_ALIASES: Record<string, string> = {
   equals: '=',
   eq: '=',
   '==': '=',
@@ -76,6 +93,15 @@ const FILTER_OPERATOR_ALIASES: Record<string, string> = {
   isnull: 'isnull',
   is_not_null: 'isnotnull',
   isnotnull: 'isnotnull',
+  // Date comparisons. `before`/`after` are CANONICAL members of the spec's
+  // `VIEW_FILTER_OPERATORS` (ui/view.zod.ts), so a stored view legitimately
+  // carries them — but they are absent from `VALID_AST_OPERATORS`
+  // (data/filter.zod.ts), which gates `isFilterAST()`. Without these two
+  // entries they reached the wire unchanged, the server's AST gate rejected
+  // the shape, and driver-sql skipped the filter ENTIRELY — an unfiltered
+  // result set with no error anywhere. objectstack#3948.
+  before: '<',
+  after: '>',
 };
 
 function normalizeFilterOperator(op: unknown): string | null {
@@ -84,15 +110,159 @@ function normalizeFilterOperator(op: unknown): string | null {
   return FILTER_OPERATOR_ALIASES[lower] ?? FILTER_OPERATOR_ALIASES[op] ?? op;
 }
 
+/**
+ * A filter entry this adapter cannot translate into an AST tuple.
+ *
+ * Thrown rather than skipped. Dropping one entry out of an `and` WIDENS the
+ * result set, and dropping the last one emits no `filter=` at all — every row,
+ * no error, from a query that asked for a subset. That is the same silent
+ * over-fetch the server-side drivers stopped doing in objectstack#3948, and
+ * skipping it here just moves it one layer up.
+ *
+ * Carries the code and status the data API uses for its own version of this
+ * refusal (objectstack#4121) so a failed list renders "this view's filter is
+ * malformed" rather than "check your connection" (#3066).
+ */
+export class MalformedFilterError extends Error {
+  readonly code = 'INVALID_FILTER';
+  readonly httpStatus = 400;
+  readonly entry: unknown;
+  readonly index: number;
+  constructor(entry: unknown, index: number) {
+    const shown = JSON.stringify(entry) ?? String(entry);
+    super(
+      `Filter entry ${index} is not a usable filter rule (${shown}). `
+      + 'Expected { field, operator, value } with a non-empty field.',
+    );
+    this.name = 'MalformedFilterError';
+    this.entry = entry;
+    this.index = index;
+  }
+}
+
+/** Detect the malformed-filter refusal, whether raised here or by the server. */
+export function isMalformedFilterError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false;
+  const e = error as Record<string, unknown>;
+  return e.code === 'INVALID_FILTER' || e.name === 'MalformedFilterError';
+}
+
 function objectFilterEntryToAST(entry: any): [string, string, any] | null {
   if (!entry || typeof entry !== 'object') return null;
-  const field = entry.field ?? entry.name;
+  // `field` only. A `?? entry.name` fallback lived here from the day the
+  // function was written (4b93db4e6) and was unreachable for exactly as long:
+  // the shape sniff below has always keyed on `field`, so a `name`-keyed entry
+  // fell through to the "already AST" branch and shipped raw. The spec agrees
+  // it is not a real shape — `ViewFilterRuleSchema.field` is required, so a
+  // `name`-keyed rule cannot be saved as view metadata in the first place.
+  const field = entry.field;
   const rawOp = entry.operator ?? entry.op ?? '=';
   const op = normalizeFilterOperator(rawOp);
   if (!field || !op) return null;
   return [String(field), op, entry.value];
 }
 
+/**
+ * Which of the two array filter shapes is this — object entries or an AST node?
+ *
+ * One definition on purpose. This test used to be written out twice (here and
+ * inline in `convertQueryParams`) and the copies had already drifted: the
+ * inline one omitted the `!== null` guard, so a `$filter` of `[null]` threw a
+ * TypeError on the plain `find()` path while the same value was handled on the
+ * `$expand` path. Same stored view, different answer, decided by whether it
+ * happened to expand a lookup.
+ */
+function isObjectFilterEntryForm(filter: readonly unknown[]): boolean {
+  const first = filter[0];
+  return filter.length > 0
+    && typeof first === 'object'
+    && first !== null
+    && !Array.isArray(first)
+    && (first as any).field !== undefined;
+}
+
+/**
+ * Translate `[{ field, operator, value }, ...]` into a filter AST node. Every
+ * entry must translate; see `MalformedFilterError` for why one that doesn't is
+ * an error rather than an omission.
+ */
+function objectFilterEntriesToAST(entries: readonly unknown[]): unknown[] {
+  const nodes = entries.map((entry, i) => {
+    // An entry that is itself an array is already a node — a mixed array keeps
+    // both conditions instead of losing one to a drop or the whole query to an
+    // error.
+    if (Array.isArray(entry)) return translateFilterChild(entry);
+    const tuple = objectFilterEntryToAST(entry);
+    if (!tuple) throw new MalformedFilterError(entry, i);
+    return tuple;
+  });
+  return nodes.length === 1 ? (nodes[0] as unknown[]) : ['and', ...nodes];
+}
+
+/** Logical heads `parseFilterAST` recognizes (`data/filter.zod.ts`). No `not`. */
+const LOGICAL_AST_HEADS = new Set(['and', 'or']);
+
+/**
+ * Translate a filter array at EVERY level, not just the top one.
+ *
+ * Translating only the top level left the commonest composite filter there is
+ * shipping raw. A list whose view carries a stored filter and whose user adds
+ * one in the panel produces `['and', <ViewFilterRule[]>, <AST tuples>]`; the
+ * head is the string `and`, so the old top-level-only check called the whole
+ * thing "already AST" and sent the rules on untouched.
+ *
+ * What the server does with that depends on its version, and both answers are
+ * wrong:
+ *
+ * ```
+ * const n = ['and', [{ field: 'stage', operator: 'eq', value: 'won' }], [['amount', '>', 1]]];
+ * isFilterAST(n)    // false — a bare rule object is not an AST child
+ * parseFilterAST(n) // { amount: { $gt: 1 } }   ← `stage = won` is simply GONE
+ * ```
+ *
+ * Since objectstack#4121 the `isFilterAST` gate turns that into a 400 and the
+ * list fails to load. Before it — or anywhere `parseFilterAST` is reached
+ * without the gate — the view's own condition is dropped without a word and the
+ * list shows records the view exists to exclude.
+ */
+function translateFilterArray(filter: unknown[]): unknown[] {
+  if (isObjectFilterEntryForm(filter)) return objectFilterEntriesToAST(filter);
+  const head = filter[0];
+  if (typeof head === 'string' && LOGICAL_AST_HEADS.has(head.toLowerCase())) {
+    return [head, ...filter.slice(1).map(translateFilterChild)];
+  }
+  // Legacy flat array of child nodes: [[...], [...]] — implicit AND.
+  if (filter.every((child) => Array.isArray(child))) return filter.map(translateFilterChild);
+  // A comparison tuple, or a shape we do not recognize. Leave it alone; the
+  // server decides, and since objectstack#4121 it says so with a 400.
+  return filter;
+}
+
+/**
+ * A child of a logical node: another array node, a bare rule object, or a value
+ * we leave alone.
+ *
+ * The bare-rule case comes from producers that SPREAD a `ViewFilterRule[]` into
+ * an `and` (`['and', ...rules, ...tuples]`) instead of wrapping it. That puts
+ * rule objects where the AST expects nodes, and the server has no good answer:
+ * `isFilterAST` rejects it (a 400 since objectstack#4121), while
+ * `parseFilterAST` reads the rule as a MongoDB condition and filters on columns
+ * literally named `field` / `operator` / `value` — three columns that do not
+ * exist, so the honest-looking result is empty.
+ *
+ * Only rule-SHAPED objects are translated: a child with no `field` is a genuine
+ * MongoDB condition (`{ status: 'active' }`) and must pass through untouched.
+ * Same discriminator `isObjectFilterEntryForm` uses at the top level.
+ */
+function translateFilterChild(child: unknown): unknown {
+  if (Array.isArray(child)) return child.length > 0 ? translateFilterArray(child) : child;
+  if (child && typeof child === 'object' && (child as any).field !== undefined) {
+    const tuple = objectFilterEntryToAST(child);
+    if (tuple) return tuple;
+  }
+  return child;
+}
+
 /**
  * Translate any of the filter shapes accepted by ObjectUI into the AST format
  * understood by the ObjectStack server's `parseFilterAST()`.
@@ -112,30 +282,68 @@ function translateFilterToAST(filter: unknown): unknown | undefined {
 
   if (Array.isArray(filter)) {
     if (filter.length === 0) return undefined;
-
-    // Object form: [{ field, operator, value }, ...]
-    const first = filter[0];
-    const isObjectForm = filter.length > 0
-      && typeof first === 'object'
-      && first !== null
-      && !Array.isArray(first)
-      && (first as any).field !== undefined;
-    if (isObjectForm) {
-      const tuples = (filter as any[])
-        .map(entry => objectFilterEntryToAST(entry))
-        .filter((t): t is [string, string, any] => t !== null);
-      if (tuples.length === 0) return undefined;
-      if (tuples.length === 1) return tuples[0];
-      return ['and', ...tuples];
-    }
-
-    // Already AST — pass through.
-    return filter;
+    return translateFilterArray(filter);
   }
 
   if (typeof filter === 'object') {
     if (Object.keys(filter as Record<string, unknown>).length === 0) return undefined;
-    return filter;
+    // Same conversion `convertQueryParams` applies. This branch used to return
+    // the object VERBATIM, so the two `find()` routes disagreed about the same
+    // filter — decided, as ever, by whether the query happened to expand a
+    // lookup. Measured across 21 operator shapes, four diverged; the one that
+    // mattered is that `convertFiltersToAST`'s unknown-operator guard — added
+    // expressly "to avoid silent failure" — never ran on this route, so a typo'd
+    // operator threw on a plain read and shipped silently on an expanded one.
+    return convertFiltersToAST(filter as Record<string, unknown>);
+  }
+
+  return undefined;
+}
+
+/**
+ * Serialize a `$orderby` to the server's `sort` shorthand
+ * (`field,-other_field`), for every shape `QueryParams['$orderby']` declares.
+ *
+ * The type declares four — `string`, `string[]`, `SortNode[]`,
+ * `Record<field, direction>` — and the two `find()` routes each open-coded a
+ * fold that handled three of them. The missing one was the bare string, and it
+ * did not degrade quietly: `Object.entries('name asc')` enumerates a string's
+ * character indices, so the request went out as `sort=0,1,2,3,4,5,6,7`. Against
+ * a server that rejects an unreadable sort rather than ignoring it
+ * (objectstack#4226), that is a `400 INVALID_SORT` and an empty list — so a
+ * standalone `ObjectGrid` with a `sort` in its metadata, which is exactly the
+ * shape it builds (`ObjectGrid.tsx`: `` `${field} ${order}` ``), failed to load
+ * at all.
+ *
+ * One serializer for both routes, for the reason the filter path already has
+ * one: two copies of a fold can only agree by inspection, and these two did not.
+ *
+ * Returns `undefined` when nothing is sortable, so callers skip the parameter
+ * entirely rather than sending an empty one.
+ */
+export function serializeOrderBy(orderby: QueryParams['$orderby']): string | undefined {
+  if (orderby === undefined || orderby === null) return undefined;
+
+  // `field asc` / `-field` / a comma-separated list of either — already the
+  // wire shorthand the server parses, so it rides through untouched.
+  if (typeof orderby === 'string') {
+    const trimmed = orderby.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+  }
+
+  const shorthand = (field: string, order?: unknown) =>
+    String(order).toLowerCase() === 'desc' ? `-${field}` : field;
+
+  if (Array.isArray(orderby)) {
+    const parts = orderby
+      .map((item) => (typeof item === 'string' ? item.trim() : shorthand(item.field, item.order)))
+      .filter((s) => s.length > 0);
+    return parts.length > 0 ? parts.join(',') : undefined;
+  }
+
+  if (typeof orderby === 'object') {
+    const parts = Object.entries(orderby).map(([field, order]) => shorthand(field, order));
+    return parts.length > 0 ? parts.join(',') : undefined;
   }
 
   return undefined;
@@ -173,6 +381,44 @@ export function clearSharedDiscoveryCache(): void {
   discoveryCache.clear();
 }
 
+/**
+ * Read the cross-object atomic-batch capability from a `discovery` document
+ * (framework #3298 / objectui #2693). The server advertises it hierarchically
+ * under `capabilities.transactionalBatch.enabled`; the published
+ * `@objectstack/client` also accepts the flat `capabilities.transactionalBatch:
+ * boolean` form and normalizes the two — mirror that here so the adapter reads
+ * the same bit regardless of which shape reaches it.
+ *
+ * Returns:
+ *   - `true`  — the backend GUARANTEES an atomic `/batch` (declared === enforced,
+ *     i.e. the route is mounted AND the runtime can honour a transaction): the
+ *     client may drop its non-atomic fallback and treat any batch failure as a
+ *     real error.
+ *   - `false` — the backend explicitly does NOT (route absent, or a runtime that
+ *     can't open a transaction).
+ *   - `undefined` — the capability is absent, i.e. the backend predates #3298;
+ *     the caller must keep the legacy runtime-probe fallback (we can't tell
+ *     whether `/batch` exists without trying it).
+ */
+export function readTransactionalBatchCapability(
+  discovery: unknown,
+): boolean | undefined {
+  const caps = (discovery as { capabilities?: unknown } | null | undefined)?.capabilities;
+  if (!caps || typeof caps !== 'object') return undefined;
+  const value = (caps as Record<string, unknown>).transactionalBatch;
+  // Flat form: `{ transactionalBatch: true }`.
+  if (typeof value === 'boolean') return value;
+  // Hierarchical form: `{ transactionalBatch: { enabled: true } }`.
+  if (
+    value &&
+    typeof value === 'object' &&
+    typeof (value as { enabled?: unknown }).enabled === 'boolean'
+  ) {
+    return (value as { enabled: boolean }).enabled;
+  }
+  return undefined;
+}
+
 /**
  * Detect "missing resource" errors regardless of where they originate.
  *
@@ -189,7 +435,108 @@ export function is404Error(error: unknown): boolean {
     return true;
   }
   const code = typeof err.code === 'string' ? err.code : '';
-  return code === 'object_not_found' || code === 'record_not_found';
+  return errorCodeIsAnyOf({ code }, ['OBJECT_NOT_FOUND', 'RECORD_NOT_FOUND']);
+}
+
+/**
+ * Thrown when the deployment has no analytics capability installed
+ * (framework#3891 / #4019).
+ *
+ * The framework retired its degraded in-kernel analytics fallback — it dropped
+ * the caller's RLS/tenant scope and ignored the contract filter, so it answered
+ * 200 with over-broad numbers. `@objectstack/service-analytics` is now the
+ * domain's only implementation, and a deployment without it answers:
+ *
+ *   - `POST /api/v1/analytics/query` → **404** (the routes aren't even mounted);
+ *   - `POST /api/v1/analytics/dataset/query` → **501 NOT_IMPLEMENTED**.
+ *
+ * Neither is a bug to report as a stack trace: it is a deployment that hasn't
+ * installed the capability. This error carries a message a UI can show as-is.
+ */
+export class AnalyticsNotInstalledError extends Error {
+  readonly code = 'ANALYTICS_NOT_INSTALLED';
+  /** The surface that was unavailable, for the message a host renders. */
+  readonly surface: string;
+  constructor(surface: string, detail?: string) {
+    super(
+      `Analytics capability is not installed on this deployment — ${surface} is unavailable. ` +
+      'Install @objectstack/service-analytics and mount AnalyticsServicePlugin to enable it.' +
+      (detail ? ` (server said: ${detail})` : ''),
+    );
+    this.name = 'AnalyticsNotInstalledError';
+    this.surface = surface;
+  }
+}
+
+/** True when `error` is an {@link AnalyticsNotInstalledError} (or its wire twin). */
+export function isAnalyticsNotInstalledError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false;
+  return (error as { code?: unknown }).code === 'ANALYTICS_NOT_INSTALLED';
+}
+
+/**
+ * Thrown when the server REJECTED the analytics query body (HTTP 400 —
+ * `VALIDATION_FAILED` since framework#4010 validates `/analytics/query` at the
+ * entry against the canonical bare `AnalyticsQuery` shape).
+ *
+ * Distinct from {@link AnalyticsNotInstalledError} on purpose: this one is a
+ * defect in what WE sent, so it must never be answered with the client-side
+ * fallback. Numbers produced by a different code path would look plausible and
+ * bury the contract violation — the misdirection framework#3878 documented.
+ */
+export class AnalyticsQueryRejectedError extends Error {
+  readonly code = 'ANALYTICS_QUERY_REJECTED';
+  /** The server's own error code (e.g. `VALIDATION_FAILED`), when it sent one. */
+  readonly serverCode?: string;
+  constructor(detail?: string, serverCode?: string) {
+    super(
+      `Analytics rejected the query: ${detail ?? 'the request body does not match the AnalyticsQuery contract'}`,
+    );
+    this.name = 'AnalyticsQueryRejectedError';
+    this.serverCode = serverCode;
+  }
+}
+
+/**
+ * Classify a FAILED analytics call so the caller knows whether to degrade or
+ * to surface the failure.
+ *
+ * `@objectstack/client`'s fetch wrapper throws on a non-2xx, decorating the
+ * error with the semantic `code` string and the numeric `httpStatus` (the
+ * ADR-0112 / framework#3842 shape this repo already reads elsewhere). Two
+ * outcomes must NOT be conflated:
+ *
+ *   - **`not-installed`** — the deployment has no analytics service. Since
+ *     framework#3891 retired the degraded in-kernel shim, that is a 404 (the
+ *     routes aren't mounted at all, framework#4019) or a 501 `NOT_IMPLEMENTED`
+ *     (REST's dataset route with no service behind it). Degrading to a
+ *     client-side aggregate over a scoped `find()` is CORRECT here.
+ *   - **`rejected`** — the server refused OUR body (400 `VALIDATION_FAILED`;
+ *     framework#4010 validates `/analytics/query` at the entry). Degrading
+ *     would answer our own contract violation with plausible numbers from a
+ *     different code path and bury it — the misdirection framework#3878
+ *     documented. It must be surfaced.
+ *
+ * Anything else (5xx, network) is `unknown`: degrade, but silently — it is a
+ * transient failure, not a deployment that is missing a capability.
+ */
+export function classifyAnalyticsFailure(
+  error: unknown,
+): { kind: 'not-installed' | 'rejected' | 'unknown'; code?: string; message?: string } {
+  const err = (error ?? {}) as Record<string, unknown>;
+  const code = typeof err.code === 'string' ? err.code : undefined;
+  const message = typeof err.message === 'string' ? err.message : undefined;
+  const status =
+    typeof err.httpStatus === 'number' ? err.httpStatus
+    : typeof err.status === 'number' ? err.status
+    : typeof err.statusCode === 'number' ? err.statusCode
+    : undefined;
+
+  if (code === 'VALIDATION_FAILED' || status === 400) return { kind: 'rejected', code, message };
+  if (status === 404 || status === 501 || code === 'NOT_IMPLEMENTED' || code === 'ROUTE_NOT_FOUND') {
+    return { kind: 'not-installed', code, message };
+  }
+  return { kind: 'unknown', code, message };
 }
 
 /**
@@ -235,17 +582,55 @@ export function isConcurrentUpdateError(error: unknown): error is ConcurrentUpda
 }
 
 /**
- * Convert any error thrown by the upstream client into a typed
- * `ConcurrentUpdateError` when it represents a 409 CONCURRENT_UPDATE.
- * Returns the original error untouched otherwise. Callers can simply
- * `throw normaliseClientError(err)` from their catch blocks.
+ * Convert any error thrown by the upstream client into a typed error when we
+ * recognise its shape. Returns the original error untouched otherwise, so
+ * callers can simply `throw normaliseClientError(err)` from their catch blocks.
+ *
+ * Two shapes are recognised:
+ *   - `409` + `CONCURRENT_UPDATE` → {@link ConcurrentUpdateError};
+ *   - `400` + `VALIDATION_FAILED` → {@link ValidationError}, carrying the
+ *     server's per-field entries so a form can mark the offending inputs
+ *     instead of showing one undirected toast.
  */
 export function normaliseClientError(error: unknown): unknown {
   if (!error || typeof error !== 'object') return error;
   const e = error as Record<string, unknown>;
+  // The client sets `details` to the parsed body's `details`, falling back to
+  // the WHOLE body — and the validation envelope has no `details` key, so this
+  // is where `fields[]` lands.
+  const details = (e.details ?? {}) as Record<string, unknown>;
+
+  if (e.code === 'VALIDATION_FAILED' || e.name === 'ValidationError') {
+    const rawFields = Array.isArray(details.fields)
+      ? details.fields
+      : Array.isArray((e as { fields?: unknown }).fields)
+        ? ((e as { fields: unknown[] }).fields)
+        : [];
+    const validationErrors = rawFields
+      .map((f) => {
+        const rec = (f ?? {}) as Record<string, unknown>;
+        const field = typeof rec.field === 'string' ? rec.field : undefined;
+        if (!field) return null;
+        const message =
+          typeof rec.message === 'string' && rec.message.trim()
+            ? rec.message
+            : typeof rec.code === 'string'
+              ? rec.code
+              : '';
+        return { field, message };
+      })
+      .filter((x): x is { field: string; message: string } => x !== null);
+
+    return new ValidationError(
+      typeof e.message === 'string' ? e.message : 'Validation failed',
+      validationErrors[0]?.field,
+      validationErrors,
+      { fields: rawFields },
+    );
+  }
+
   if (e.code !== 'CONCURRENT_UPDATE' && e.httpStatus !== 409) return error;
   if (e.code !== 'CONCURRENT_UPDATE') return error;
-  const details = (e.details ?? {}) as Record<string, unknown>;
   return new ConcurrentUpdateError({
     currentVersion: typeof details.currentVersion === 'string' ? details.currentVersion : null,
     currentRecord: details.currentRecord ?? null,
@@ -271,7 +656,7 @@ function createQuietHttpLogger(): any {
     const errBody = meta.error;
     if (errBody && typeof errBody === 'object') {
       const code = (errBody as Record<string, unknown>).code;
-      if (code === 'object_not_found' || code === 'record_not_found') return true;
+      if (errorCodeIsAnyOf({ code }, ['OBJECT_NOT_FOUND', 'RECORD_NOT_FOUND'])) return true;
     }
     return false;
   };
@@ -333,6 +718,36 @@ export type ConnectionStateListener = (event: ConnectionStateEvent) => void;
  */
 export 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.
+ */
+export 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
+ * supplied fields never landed, so the UI can tell the user rather than let it
+ * pass silently. Subscribe via {@link ObjectStackAdapter.onWriteWarning}.
+ */
+export interface WriteWarningEvent {
+  operation: 'create' | 'update';
+  resource: string;
+  id?: string | number;
+  droppedFields: DroppedFieldsEvent[];
+}
+
+/** Event listener type for write-warning (dropped-fields) events. */
+export type WriteWarningListener = (event: WriteWarningEvent) => void;
+
 // Re-export FileUploadResult from types for consumers
 export type { FileUploadResult } from '@object-ui/types';
 
@@ -393,6 +808,8 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
   private reconnectAttempts: number = 0;
   private baseUrl: string;
   private token?: string;
+  /** One "analytics capability is missing" console line per adapter, not per widget. */
+  private analyticsCapabilityWarned = false;
   private fetchImpl: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
   // In-flight find() requests keyed by resource + serialized params.
   // Coalesces concurrent identical reads (e.g. React StrictMode double-mount,
@@ -404,11 +821,31 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
   // so optional collections like sys_presence don't hammer the server with
   // failing requests on every record open / panel render.
   private missingResources = new Set<string>();
+  // Set once the server has told us it can't do a cross-object transactional
+  // batch (the client SDK's data.batchTransaction threw HTTP 404/405/501). After
+  // that, batchTransaction skips the SDK call and serves every call via the
+  // client-side emulation — the non-atomic fallback lives HERE, isolated to the
+  // one adapter that has to cope with a backend lacking server atomicity (#2679).
+  private batchUnsupported = false;
+  // The server's declared cross-object atomic-batch capability, read from
+  // discovery at connect() (framework #3298 / objectui #2693). `true` → the
+  // backend GUARANTEES an atomic `/batch`, so batchTransaction trusts it and
+  // never degrades to the non-atomic emulation (any failure surfaces as a real
+  // error). `false` or `undefined` (capability absent → backend predates #3298)
+  // → keep the legacy runtime-probe + emulation fallback so a save is still
+  // possible; dropping it there would turn "saves, less safe" into "no save
+  // path" on older backends (#2679 compatibility constraint).
+  private atomicBatchCapability: boolean | undefined;
   // Subscribers registered via onMutation(). Emitted after each successful
   // create/update/delete so data-bound views (ListView, ObjectView, kanban,
   // calendar) auto-refresh — the interface ListView relies on to reflect
   // inline-edit "Save All" writes without a manual reload.
-  private mutationListeners = new Set<(event: MutationEvent<T>) => void>();
+  private mutationListeners = new Set<(event: DataSourceMutationEvent<T>) => void>();
+
+  // Subscribers registered via onWriteWarning(). Emitted after a create/update
+  // whose response carried `droppedFields` (framework #3431/#3455) so the app
+  // shell can surface a toast instead of the strip passing silently.
+  private writeWarningListeners = new Set<WriteWarningListener>();
 
   constructor(config: {
     baseUrl: string;
@@ -479,6 +916,11 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         // helpers continue to work without a redundant fetch.
         (this.client as unknown as { discoveryInfo?: unknown }).discoveryInfo = data;
 
+        // Record the declared cross-object atomic-batch capability (#3298) so
+        // batchTransaction can decide declaratively at call time whether it may
+        // trust server atomicity instead of runtime-probing 404/405/501.
+        this.atomicBatchCapability = readTransactionalBatchCapability(data);
+
         this.connected = true;
         this.reconnectAttempts = 0;
         this.setConnectionState('connected');
@@ -663,6 +1105,103 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     return promise;
   }
 
+  /**
+   * Full-text search across every searchable object in a single round-trip.
+   *
+   * Hits `GET /api/v1/search?q=`, the platform's global search endpoint served
+   * by the registered search service (the pinyin full-text plugin) and backed
+   * by `metadata-protocol`'s `searchAll`. Unlike `find(resource, { $search })`
+   * — a per-object metadata-driven search (ADR-0061) — this consults the search
+   * index and ranks hits across objects, so it surfaces records the per-object
+   * fanout misses. Global affordances (⌘K command palette, search page) prefer
+   * this path (framework #3371).
+   *
+   * Returns `{ query, hits }`. A backend without the search plugin installed
+   * answers `404`; we treat that as "no global search here" and return an empty
+   * hit set so callers can fall back to a per-object fanout rather than surface
+   * an error.
+   */
+  async searchAll(
+    query: string,
+    options?: { limit?: number; objects?: string[] },
+  ): Promise<GlobalSearchResult> {
+    const trimmed = (query ?? '').trim();
+    if (trimmed === '') return { query: '', hits: [] };
+
+    await this.connect();
+
+    const queryParams = new URLSearchParams();
+    queryParams.set('q', trimmed);
+    if (options?.limit != null && options.limit > 0) {
+      queryParams.set('limit', String(options.limit));
+    }
+    if (options?.objects && options.objects.length > 0) {
+      queryParams.set('objects', options.objects.join(','));
+    }
+
+    const baseUrl = (this.baseUrl || '').replace(/\/$/, '');
+    // Avoid doubling /api/v1 when baseUrl already carries the version suffix.
+    const hasApiVersionSuffix = /\/api\/v\d+$/i.test(baseUrl);
+    const searchPath = hasApiVersionSuffix ? '/search' : '/api/v1/search';
+    const url = `${baseUrl}${searchPath}?${queryParams.toString()}`;
+
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    };
+    if (this.token) {
+      headers['Authorization'] = `Bearer ${this.token}`;
+    }
+
+    const res = await this.fetchImpl(url, { method: 'GET', headers });
+
+    if (!res.ok) {
+      // 404 → the search plugin isn't installed on this backend. Degrade to an
+      // empty result so the caller can fall back instead of hard-failing.
+      if (res.status === 404) return { query: trimmed, hits: [] };
+      const errorBody = await res.json().catch(() => ({ message: res.statusText }));
+      const err = new Error(
+        errorBody?.error?.message || errorBody?.message || res.statusText,
+      ) as Error & { status?: number };
+      err.status = res.status;
+      throw err;
+    }
+
+    const body = await res.json();
+    // Unwrap the standard `{ success, data }` envelope when present; the search
+    // endpoint itself returns `{ query, hits }`.
+    const payload =
+      body && typeof body === 'object' && typeof body.success === 'boolean' && 'data' in body
+        ? body.data
+        : body;
+
+    const rawHits: unknown[] = Array.isArray(payload?.hits)
+      ? payload.hits
+      : Array.isArray(payload)
+        ? payload
+        : [];
+
+    const hits: GlobalSearchHit[] = [];
+    for (const entry of rawHits) {
+      if (!entry || typeof entry !== 'object') continue;
+      const h = entry as Record<string, any>;
+      const object = h.object ?? h.objectName ?? h.object_name;
+      const id = h.id ?? h.record?.id ?? h.record?._id;
+      if (typeof object !== 'string' || id == null) continue;
+      hits.push({
+        object,
+        id: String(id),
+        title: typeof h.title === 'string' ? h.title : undefined,
+        snippet: typeof h.snippet === 'string' ? h.snippet : undefined,
+        record: h.record && typeof h.record === 'object' ? h.record : undefined,
+      });
+    }
+
+    return {
+      query: typeof payload?.query === 'string' ? payload.query : trimmed,
+      hits,
+    };
+  }
+
   /**
    * Find a single record by ID.
    */
@@ -716,7 +1255,7 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
    * Notify all mutation subscribers. A throwing listener must not break the
    * mutation or starve the other subscribers, so each is isolated.
    */
-  private emitMutation(event: MutationEvent<T>): void {
+  private emitMutation(event: DataSourceMutationEvent<T>): void {
     for (const listener of this.mutationListeners) {
       try {
         listener(event);
@@ -732,18 +1271,110 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
    * mutation (e.g. inline-edit "Save All", which writes through `update` and
    * must repaint the list without a manual reload).
    */
-  onMutation(callback: (event: MutationEvent<T>) => void): () => void {
+  onMutation(callback: (event: DataSourceMutationEvent<T>) => void): () => void {
     this.mutationListeners.add(callback);
     return () => {
       this.mutationListeners.delete(callback);
     };
   }
 
+  /**
+   * Notify all write-warning subscribers. Isolated like {@link emitMutation}: a
+   * throwing listener must not break the write or starve the others.
+   */
+  private emitWriteWarning(event: WriteWarningEvent): void {
+    for (const listener of this.writeWarningListeners) {
+      try {
+        listener(event);
+      } catch (err) {
+        console.warn('ObjectStackAdapter: write-warning listener error', err);
+      }
+    }
+  }
+
+  /**
+   * Read `droppedFields` off a create/update response (framework #3431/#3455)
+   * and, when present, notify write-warning subscribers. Tolerant of a client
+   * 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.
+   */
+  private notifyDroppedFields(
+    operation: 'create' | 'update',
+    resource: string,
+    result: unknown,
+    id?: string | number,
+  ): void {
+    const dropped = (result as { droppedFields?: unknown } | null | undefined)?.droppedFields;
+    if (!Array.isArray(dropped) || dropped.length === 0) return;
+    const droppedFields = dropped.filter(
+      (e): e is DroppedFieldsEvent =>
+        !!e && typeof e === 'object' && Array.isArray((e as DroppedFieldsEvent).fields) && (e as DroppedFieldsEvent).fields.length > 0,
+    );
+    if (droppedFields.length === 0) return;
+    this.emitWriteWarning({ operation, resource, ...(id !== undefined ? { id } : {}), droppedFields });
+  }
+
+  /**
+   * Same, for the cross-object transactional batch (framework #3794). Its
+   * response hangs the events off a top-level `droppedFields` list, each tagged
+   * with the `index` of the operation it came from — `results` entries are bare
+   * record echoes with nowhere to hang a per-row list.
+   *
+   * This is the path that matters most for the warning: `batchTransaction` is
+   * how the console's record form saves a master-detail record, so a
+   * `readonlyWhen`-locked field edited in that form was stripped server-side
+   * while the UI reported a plain success. The operation kind is taken from the
+   * originating op so the toast doesn't call an update a create.
+   */
+  private notifyBatchDroppedFields(
+    operations: BatchTransactionOperation[],
+    payload: unknown,
+  ): void {
+    const dropped = (payload as { droppedFields?: unknown } | null | undefined)?.droppedFields;
+    if (!Array.isArray(dropped) || dropped.length === 0) return;
+    for (const entry of dropped) {
+      if (!entry || typeof entry !== 'object') continue;
+      const e = entry as DroppedFieldsEvent & { index?: number };
+      if (!Array.isArray(e.fields) || e.fields.length === 0) continue;
+      const op = typeof e.index === 'number' ? operations[e.index] : undefined;
+      // `delete` never drops fields; anything unexpected reads as an update,
+      // which is the truthful default for a batch that echoed a strip.
+      const operation: 'create' | 'update' = (op?.action ?? 'create') === 'create' ? 'create' : 'update';
+      this.emitWriteWarning({
+        operation,
+        resource: e.object ?? op?.object ?? '',
+        ...(op?.id !== undefined && op?.id !== null ? { id: op.id } : {}),
+        droppedFields: [{ object: e.object, fields: e.fields, reason: e.reason }],
+      });
+    }
+  }
+
+  /**
+   * Subscribe to write-warning events (a create/update dropped caller-supplied
+   * fields — #3431/#3455). Returns an unsubscribe function. The app shell uses
+   * this to toast the user; the write itself already succeeded.
+   */
+  onWriteWarning(callback: WriteWarningListener): () => void {
+    this.writeWarningListeners.add(callback);
+    return () => {
+      this.writeWarningListeners.delete(callback);
+    };
+  }
+
   async create(resource: string, data: Partial<T>): Promise<T> {
     await this.connect();
-    const result = await this.client.data.create<T>(resource, data);
-    this.emitMutation({ type: 'create', resource, record: { ...result.record } });
-    return result.record;
+    try {
+      const result = await this.client.data.create<T>(resource, data);
+      this.emitMutation({ type: 'create', resource, record: { ...result.record } });
+      this.notifyDroppedFields('create', resource, result, (result.record as { id?: string | number } | undefined)?.id);
+      return result.record;
+    } catch (err) {
+      // `update` has always normalised; `create` did not, so a rejected insert
+      // reached callers as the raw client error — no typed shape to branch on,
+      // and its `fields[]` unreachable. A create is the path that most often
+      // trips required-field validation, so it needs this more, not less.
+      throw normaliseClientError(err);
+    }
   }
 
   /**
@@ -772,6 +1403,7 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         opts?.ifMatch ? { ifMatch: opts.ifMatch } : undefined,
       );
       this.emitMutation({ type: 'update', resource, id, record: { ...result.record } });
+      this.notifyDroppedFields('update', resource, result, id);
       return result.record;
     } catch (err) {
       throw normaliseClientError(err);
@@ -927,42 +1559,120 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
    * @returns Promise resolving to array of results
    */
   /**
-   * Cross-object transactional batch (ObjectStack #1604). Runs the operations
-   * in ONE server transaction — commit all or roll back all. A field value of
-   * `{ $ref: <earlier op index> }` resolves to that op's created id, so a child
-   * can reference its parent created earlier in the same batch (master-detail).
+   * Cross-object transactional batch (ObjectStack #1604 / ADR-0034 item 4).
+   * Runs the operations in ONE server transaction — commit all or roll back
+   * all. A field value of `{ $ref: <earlier op index> }` resolves to that op's
+   * created id, so a child can reference its parent created earlier in the same
+   * batch (master-detail).
+   *
+   * Transport: the published `@objectstack/client` SDK method
+   * `data.batchTransaction` (framework #3271; shipped since client v16, our
+   * dependency floor). Per AGENTS.md §7 data always flows through the client —
+   * never a hand-rolled `fetch('/api/v1/batch')`.
+   *
+   * Fallback decision — declarative capability negotiation (framework #3298 /
+   * objectui #2693). At connect() we read `capabilities.transactionalBatch`
+   * from discovery:
+   *   - Declared `true` → the backend GUARANTEES atomicity (declared ===
+   *     enforced). We TRUST it: any batch failure — including 404/405/501 —
+   *     surfaces as a real error. No non-atomic client-side compensation. This
+   *     is the path modern backends take.
+   *   - Declared `false`, or ABSENT (backend predates #3298) → we can't rely on
+   *     server atomicity, so we keep the legacy behaviour: on 404/405 (no
+   *     endpoint) or 501 (runtime without transactions) degrade to the
+   *     client-side, NON-atomic {@link emulateBatchTransaction} so a save is
+   *     still possible. Removing that here would regress older backends from
+   *     "saves, less safe" to "no save path" (#2679 compatibility constraint).
+   *     The non-atomic fallback stays isolated to THIS adapter.
    */
   async batchTransaction(
-    operations: Array<{ object: string; action?: 'create' | 'update' | 'delete'; data?: any; id?: string }>,
+    operations: BatchTransactionOperation[],
   ): Promise<{ results: any[] }> {
-    const url = `${this.baseUrl}/api/v1/batch`;
-    const response = await this.fetchImpl(url, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
-      // Send the session cookie too: in the browser console auth is cookie-based
-      // (no bearer `token`), so without `credentials: 'include'` this raw fetch
-      // is unauthenticated — every master-detail batch save would 401. Bearer
-      // (server-to-server) and cookie (console) auth now both work.
-      credentials: 'include',
-      body: JSON.stringify({ operations }),
-    });
-    if (!response.ok) {
-      const error = await response.json().catch(() => ({ message: response.statusText }));
-      throw new ObjectStackError(
-        error.error || error.message || `Batch failed with status ${response.status}`,
-        'BATCH_ERROR',
-        response.status,
+    // Ensure discovery (and thus the #3298 capability) is loaded so the
+    // decision below is declarative, not "fire a batch and read the status".
+    await this.connect();
+
+    // When the backend declares atomic batch support we never degrade: a
+    // failure is a real error, not a cue to fall back. Otherwise (declared
+    // false, or capability absent on a pre-#3298 backend) the emulation
+    // fallback below stays active.
+    const guaranteed = this.atomicBatchCapability === true;
+
+    // Already degraded on a non-declaring backend — skip the SDK call.
+    // (Unreachable once `guaranteed`: that path never sets `batchUnsupported`.)
+    if (!guaranteed && this.batchUnsupported) {
+      return emulateBatchTransaction(this, operations);
+    }
+
+    try {
+      // Typed SDK method — guaranteed present by the `@objectstack/client@^16`
+      // dependency floor (framework #3271). No hand-rolled POST /api/v1/batch.
+      const payload = await this.client.data.batchTransaction(operations);
+      this.emitBatchMutations(operations, payload?.results);
+      this.notifyBatchDroppedFields(operations, payload);
+      return payload;
+    } catch (err) {
+      // On a non-declaring backend, endpoint missing (404/405) or a runtime that
+      // can't do transactions (the framework rest-server answers 501
+      // "Transactional batch not supported by this runtime") → degrade to the
+      // non-atomic client emulation so the save still goes through. When the
+      // backend DECLARED support (`guaranteed`), even these are hard errors — a
+      // server that advertised the capability must honour it. Every other status
+      // (400 validation, 401/403 auth, 409 conflict, 500 fault) is a real error
+      // the caller must see — never silently retried.
+      const status = this.errorStatusOf(err);
+      if (!guaranteed && this.batchStatusUnsupported(status)) {
+        return this.fallbackToEmulation(operations, status);
+      }
+      throw err;
+    }
+  }
+
+  /** True for statuses that mean "this backend can't do a transactional batch". */
+  private batchStatusUnsupported(status: number | undefined): boolean {
+    return status === 404 || status === 405 || status === 501;
+  }
+
+  /** Best-effort HTTP status extraction from a thrown SDK/client error. */
+  private errorStatusOf(err: unknown): number | undefined {
+    if (!err || typeof err !== 'object') return undefined;
+    const e = err as Record<string, unknown>;
+    const s = e.httpStatus ?? e.status ?? e.statusCode;
+    return typeof s === 'number' ? s : undefined;
+  }
+
+  /** Mark the endpoint unsupported (warn once) and serve via emulation. */
+  private fallbackToEmulation(
+    operations: BatchTransactionOperation[],
+    status: number | undefined,
+  ): Promise<{ results: any[] }> {
+    if (!this.batchUnsupported) {
+      this.batchUnsupported = true;
+      console.warn(
+        `ObjectStackAdapter: POST /api/v1/batch unavailable (HTTP ${status ?? '?'}) — ` +
+          'falling back to non-atomic client-side batch emulation. Cross-object ' +
+          'saves on this backend are best-effort, not transactional.',
       );
     }
-    const payload: { results: any[] } = await response.json();
-    // The whole transaction committed — emit one MutationEvent per operation so
-    // the invalidation bus (#2269) sees writes that went through /batch exactly
-    // like single create/update/delete calls (master-detail ModalForm saves
-    // otherwise leave related lists and count badges stale, #2582). `results`
-    // is index-aligned with `operations`; creates take id/record from the
-    // server echo. A failed batch rolled back entirely and throws above, so
-    // nothing is emitted for it.
-    const results = Array.isArray(payload?.results) ? payload.results : [];
+    return emulateBatchTransaction(this, operations);
+  }
+
+  /**
+   * Emit one DataSourceMutationEvent per committed operation so the invalidation bus
+   * (#2269) sees writes that went through /batch exactly like single
+   * create/update/delete calls — master-detail ModalForm saves otherwise leave
+   * related lists and count badges stale (#2582). `results` is index-aligned
+   * with `operations`; creates take id/record from the server echo.
+   *
+   * Only called on the server-committed paths. The emulation branch drives the
+   * adapter's own create/update/delete primitives, which already emit — so it
+   * must NOT be routed through here, or events would double-fire.
+   */
+  private emitBatchMutations(
+    operations: BatchTransactionOperation[],
+    rawResults: unknown,
+  ): void {
+    const results = Array.isArray(rawResults) ? rawResults : [];
     operations.forEach((op, i) => {
       const action = op.action ?? 'create';
       const echo = results[i];
@@ -974,7 +1684,6 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         this.emitMutation({ type: 'delete', resource: op.object, id: op.id });
       }
     });
-    return payload;
   }
 
   async bulk(resource: string, operation: 'create' | 'update' | 'delete', data: Partial<T>[]): Promise<T[]> {
@@ -1397,22 +2106,8 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     }
 
     // Sorting
-    if (params.$orderby) {
-      if (Array.isArray(params.$orderby)) {
-        const sortStr = params.$orderby.map(item => {
-          if (typeof item === 'string') return item;
-          const field = item.field;
-          const order = item.order || 'asc';
-          return order === 'desc' ? `-${field}` : field;
-        }).join(',');
-        queryParams.set('sort', sortStr);
-      } else {
-        const sortStr = Object.entries(params.$orderby)
-          .map(([field, order]) => order === 'desc' ? `-${field}` : field)
-          .join(',');
-        queryParams.set('sort', sortStr);
-      }
-    }
+    const sortStr = serializeOrderBy(params.$orderby);
+    if (sortStr) queryParams.set('sort', sortStr);
 
     // Filter — translate ViewFilterRule[] (`[{field, operator, value}]`)
     // and other shapes into AST tuples the server understands. Without this,
@@ -1497,6 +2192,16 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         queryParams.set('filter', JSON.stringify(translated));
       }
     }
+    // Search — the other half of what a list is showing. Without it an export
+    // taken while a search is active returns the unsearched superset
+    // (objectstack#4230). Servers predating that ignore the param.
+    const searchTerm = typeof request.search === 'string' ? request.search.trim() : '';
+    if (searchTerm) {
+      queryParams.set('search', searchTerm);
+      if (request.searchFields && request.searchFields.length > 0) {
+        queryParams.set('searchFields', request.searchFields.join(','));
+      }
+    }
 
     const baseUrl = this.baseUrl.replace(/\/$/, '');
     // Avoid doubling /api/v1 if baseUrl already includes the version suffix.
@@ -1549,51 +2254,21 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
           //      entry into the AST tuple shape and map human-readable
           //      operator names (`greater_than_or_equal`, `in`, `contains`,
           //      …) to the canonical symbols the server understands.
-          const isObjectForm = params.$filter.length > 0
-            && typeof params.$filter[0] === 'object'
-            && !Array.isArray(params.$filter[0])
-            && (params.$filter[0] as any).field !== undefined;
-          if (isObjectForm) {
-            const tuples = (params.$filter as any[])
-              .map(entry => objectFilterEntryToAST(entry))
-              .filter((t): t is [string, string, any] => t !== null);
-            if (tuples.length === 0) {
-              // All entries were unrecognized — drop the filter rather than
-              // sending a malformed array.
-            } else if (tuples.length === 1) {
-              options.filters = tuples[0];
-            } else {
-              options.filters = ['and', ...tuples];
-            }
-          } else {
-            // Already in AST format
-            options.filters = params.$filter;
-          }
+          // Shared with `translateFilterToAST` so the two `find()` routes — this
+          // one and the `$expand`/`$search` raw GET — cannot disagree about the
+          // same stored filter.
+          options.filters = translateFilterArray(params.$filter);
         } else {
           options.filters = convertFiltersToAST(params.$filter);
         }
       }
     }
 
-    // Sorting - convert to ObjectStack format
-    if (params.$orderby) {
-      if (Array.isArray(params.$orderby)) {
-        // Handle array format ['name', '-age'] or [{ field: 'name', order: 'asc' }]
-        options.sort = params.$orderby.map(item => {
-          if (typeof item === 'string') return item;
-          // Handle object format { field: 'name', order: 'desc' }
-          const field = item.field;
-          const order = item.order || 'asc';
-          return order === 'desc' ? `-${field}` : field;
-        });
-      } else {
-        // Handle Record format { name: 'asc', age: 'desc' }
-        const sortArray = Object.entries(params.$orderby).map(([field, order]) => {
-          return order === 'desc' ? `-${field}` : field;
-        });
-        options.sort = sortArray;
-      }
-    }
+    // Sorting — the same serializer the raw GET route uses, so the two `find()`
+    // paths cannot disagree about one stored sort. The client SDK's
+    // `QueryOptions.sort` accepts the shorthand string directly.
+    const sort = serializeOrderBy(params.$orderby);
+    if (sort) options.sort = sort;
 
     // Pagination
     if (params.$skip !== undefined) {
@@ -1930,32 +2605,25 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     config: Record<string, any>
   ): Promise<Record<string, any> | void> {
     await this.connect();
-    try {
-      // ADR-0005 metadata customization overlay: persist views under
-      // `type='view'` (NOT `type=<objectName>` — that was a pre-overlay
-      // misuse that hit `/api/v1/meta/<objectName>/<viewId>`, which the
-      // server never wired). The view's `data.object` field is what
-      // associates it back to the object on read.
-      const merged = { ...(config || {}), object: (config as any)?.object || objectName, name: viewId };
-      const result: any = await this.client.meta.saveItem(
-        'view',
-        viewId,
-        merged
-      );
-      // Invalidate cached read so next getView reflects the change
-      const cacheKey = `view:${objectName}:${viewId}`;
-      this.metadataCache.invalidate?.(cacheKey);
-      // Also invalidate the batch override map so listViewOverrides re-fetches
-      this.metadataCache.invalidate?.(`view-overrides:${objectName}`);
-      this.metadataCache.invalidate?.(`views:${objectName}`);
-      if (result && result.item) return result.item;
-      return result ?? undefined;
-    } catch (err) {
-      // Surface the error so the caller can decide whether to toast/log;
-      // we don't swallow it here because persistence failures are
-      // operationally meaningful (unlike read fallbacks).
-      throw err;
-    }
+    // ADR-0005 metadata customization overlay: persist views under
+    // `type='view'` (NOT `type=<objectName>` — that was a pre-overlay
+    // misuse that hit `/api/v1/meta/<objectName>/<viewId>`, which the
+    // server never wired). The view's `data.object` field is what
+    // associates it back to the object on read.
+    const merged = { ...(config || {}), object: (config as any)?.object || objectName, name: viewId };
+    const result: any = await this.client.meta.saveItem(
+      'view',
+      viewId,
+      merged
+    );
+    // Invalidate cached read so next getView reflects the change
+    const cacheKey = `view:${objectName}:${viewId}`;
+    this.metadataCache.invalidate?.(cacheKey);
+    // Also invalidate the batch override map so listViewOverrides re-fetches
+    this.metadataCache.invalidate?.(`view-overrides:${objectName}`);
+    this.metadataCache.invalidate?.(`views:${objectName}`);
+    if (result && result.item) return result.item;
+    return result ?? undefined;
   }
 
   /**
@@ -1968,13 +2636,31 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
    * Filters by `data.object === objectName` (or top-level `object`)
    * client-side because the metadata index is name-only, not field-typed.
    */
-  async listViews(objectName: string): Promise<any[]> {
+  async listViews(
+    objectName: string,
+    options?: { previewDrafts?: boolean },
+  ): Promise<any[]> {
     await this.connect();
     try {
-      const result: any = await this.client.meta.getItems('view');
-      const items: any[] = Array.isArray(result?.items)
-        ? result.items
-        : Array.isArray(result) ? result : [];
+      let items: any[];
+      if (options?.previewDrafts) {
+        // ADR-0037 + #2767 (P2/P3): a SINGLE `?preview=draft` request already
+        // returns the active+draft OVERLAID list — draft wins by name,
+        // draft-only views surface, each draft tagged `_draft: true`. So we
+        // REPLACE the published list wholesale (never fetch both and append,
+        // which double-lists a draft that edits a published view). Route it
+        // through `MetadataClient` rather than a hand-rolled fetch so the
+        // metadata route + any environment scoping stay in one place.
+        const draftItems = await this.metadataClient()
+          .withPreviewDrafts(true)
+          .list<any>('view');
+        items = Array.isArray(draftItems) ? draftItems : [];
+      } else {
+        const result: any = await this.client.meta.getItems('view');
+        items = Array.isArray(result?.items)
+          ? result.items
+          : Array.isArray(result) ? result : [];
+      }
       // This feeds the list-view switcher (ViewTabBar), so it must return
       // LIST-family views only. The backend now exposes each view as an
       // independent ViewItem carrying a `viewKind` discriminant (ADR-0017);
@@ -1993,6 +2679,10 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         return !(viewKind && FORM_FAMILY.has(viewKind));
       }).map((v: any) => {
         const spec = v.list ?? v;
+        // Preserve the draft provenance flag so the switcher can badge an
+        // unpublished view (ADR-0037). The overlay tags the item, not its
+        // nested spec, so read from either.
+        const isDraft = v._draft === true || spec?._draft === true;
         // Canonical ViewItem (ADR-0017) carries its body under `config`;
         // the display `type` (grid/kanban/gallery/…) lives at `config.type`,
         // and only the list/form *family* sits at the top level (`viewKind`).
@@ -2008,9 +2698,10 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
             name: spec.name ?? spec.config.name,
             label: spec.label ?? spec.config.label,
             isDefault: !!spec.isDefault,
+            ...(isDraft ? { _draft: true } : {}),
           };
         }
-        return spec;
+        return isDraft ? { ...spec, _draft: true } : spec;
       });
     } catch (err) {
       console.warn('[OBJECTSTACKDataSource] listViews failed:', err);
@@ -2018,6 +2709,20 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     }
   }
 
+  /**
+   * Build a {@link MetadataClient} bound to this adapter's server + auth. Used
+   * by draft-aware reads (`listViews({ previewDrafts })`) so the `/meta` route,
+   * `?preview=draft` flag, and environment scoping live in the SDK rather than
+   * being hand-assembled at each call site (#2767 P3).
+   */
+  private metadataClient(): MetadataClient {
+    return new MetadataClient({
+      baseUrl: this.baseUrl,
+      fetch: this.fetchImpl,
+      ...(this.token ? { headers: { Authorization: `Bearer ${this.token}` } } : {}),
+    });
+  }
+
   /**
    * List registered import `mapping` artifacts targeting a given object
    * (framework #2611). Reads the `mapping` metadata kind via the overlay API
@@ -2075,14 +2780,10 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
       object: spec?.object || objectName,
       data: spec?.data || { provider: 'object', object: objectName },
     };
-    try {
-      const result: any = await this.client.meta.saveItem('view', name, fullSpec);
-      this.metadataCache.invalidate?.(`views:${objectName}`);
-      if (result && result.item) return result.item;
-      return fullSpec;
-    } catch (err) {
-      throw err;
-    }
+    const result: any = await this.client.meta.saveItem('view', name, fullSpec);
+    this.metadataCache.invalidate?.(`views:${objectName}`);
+    if (result && result.item) return result.item;
+    return fullSpec;
   }
 
   /**
@@ -2112,15 +2813,11 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
       name: viewName,
       object: current?.object || (current as any)?.data?.object || objectName,
     };
-    try {
-      const result: any = await this.client.meta.saveItem('view', viewName, merged);
-      this.metadataCache.invalidate?.(`views:${objectName}`);
-      this.metadataCache.invalidate?.(`view:${objectName}:${viewName}`);
-      if (result && result.item) return result.item;
-      return merged;
-    } catch (err) {
-      throw err;
-    }
+    const result: any = await this.client.meta.saveItem('view', viewName, merged);
+    this.metadataCache.invalidate?.(`views:${objectName}`);
+    this.metadataCache.invalidate?.(`view:${objectName}:${viewName}`);
+    if (result && result.item) return result.item;
+    return merged;
   }
 
   /**
@@ -2133,14 +2830,10 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     viewName: string,
   ): Promise<{ deleted: boolean }> {
     await this.connect();
-    try {
-      const result: any = await this.client.meta.deleteItem('view', viewName);
-      this.metadataCache.invalidate?.(`views:${objectName}`);
-      this.metadataCache.invalidate?.(`view:${objectName}:${viewName}`);
-      return { deleted: !!(result?.deleted ?? result?.reset ?? true) };
-    } catch (err) {
-      throw err;
-    }
+    const result: any = await this.client.meta.deleteItem('view', viewName);
+    this.metadataCache.invalidate?.(`views:${objectName}`);
+    this.metadataCache.invalidate?.(`view:${objectName}:${viewName}`);
+    return { deleted: !!(result?.deleted ?? result?.reset ?? true) };
   }
 
 
@@ -2207,21 +2900,17 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     schema: Record<string, any>
   ): Promise<Record<string, any> | void> {
     await this.connect();
-    try {
-      const result: any = await this.client.meta.saveItem(
-        'dashboard',
-        dashboardName,
-        schema
-      );
-      // Invalidate dashboards list and any cached dashboard read so the
-      // next render reflects the change.
-      this.metadataCache.invalidate?.('dashboards');
-      this.metadataCache.invalidate?.(`dashboard:${dashboardName}`);
-      if (result && result.item) return result.item;
-      return result ?? undefined;
-    } catch (err) {
-      throw err;
-    }
+    const result: any = await this.client.meta.saveItem(
+      'dashboard',
+      dashboardName,
+      schema
+    );
+    // Invalidate dashboards list and any cached dashboard read so the
+    // next render reflects the change.
+    this.metadataCache.invalidate?.('dashboards');
+    this.metadataCache.invalidate?.(`dashboard:${dashboardName}`);
+    if (result && result.item) return result.item;
+    return result ?? undefined;
   }
 
   /**
@@ -2265,6 +2954,12 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
       const measureName = params.function === 'count'
         ? 'count'
         : `${params.field}_${params.function}`;
+      // The column the caller expects the value under — the raw `field`, or the
+      // literal `count` when a count names no field (framework#3701). Reading
+      // `params.field` directly here keyed the row `undefined` for a fieldless
+      // count and deleted the `count` the server sent, so the chart plotted
+      // nothing.
+      const valueKey = this.aggregateValueKey(params);
 
       const payload: Record<string, unknown> = {
         cube: resource,
@@ -2281,6 +2976,7 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
       }
 
       const data = await this.client.analytics.query(payload);
+
       const rawRows: any[] = Array.isArray(data) ? data
         : data?.rows && Array.isArray(data.rows) ? data.rows
         : data?.data && Array.isArray(data.data) ? data.data
@@ -2296,42 +2992,89 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
       const measureMissing = rawRows.length > 0 && rawRows.every((row: any) => {
         if (row == null) return true;
         if (measureName in row && row[measureName] != null) return false;
-        if (params.field in row && row[params.field] != null) return false;
+        if (valueKey in row && row[valueKey] != null) return false;
         return true;
       });
       if (measureMissing) {
-        const result = await this.find(resource as any, params.filter ? { $filter: params.filter } as any : undefined);
-        const records = result.data || [];
-        if (records.length === 0) return [];
-        return this.aggregateClientSide(records, params);
+        return await this.aggregateViaFind(resource, params);
       }
 
-      // Map measure keys back to the original field name so that consumers
-      // (ObjectChart, DashboardRenderer, etc.) can access values by field name.
-      // This includes count → field (e.g. 'count' → 'amount') to match the
-      // output format of aggregateClientSide() which always uses params.field.
+      // Map measure keys back to the object-bound result column so consumers
+      // (ObjectChart, DashboardRenderer, …) read values by the name the
+      // convention promises: `field`, or `count` for a fieldless count
+      // (framework#3701). This includes count → field (e.g. 'count' →
+      // 'amount'), matching aggregateClientSide()'s output.
       return rawRows.map((row: any) => {
         const mapped = { ...row };
-        if (measureName !== params.field && measureName in mapped) {
-          mapped[params.field] = mapped[measureName];
+        if (measureName !== valueKey && measureName in mapped) {
+          mapped[valueKey] = mapped[measureName];
           delete mapped[measureName];
         }
         return mapped;
       });
-    } catch {
-      // If the analytics endpoint is not available, fall back to
-      // find() + client-side aggregation. Crucially, forward the same
-      // filter so the fallback aggregates over the SAME row set the
-      // server-side analytics query would have — otherwise the KPI
-      // silently sums the whole table and lies to the user.
-      const result = await this.find(resource as any, params.filter ? { $filter: params.filter } as any : undefined);
-      const records = result.data || [];
-      if (records.length === 0) return [];
+    } catch (e) {
+      const failure = classifyAnalyticsFailure(e);
+
+      // The server refused OUR body — that is a defect in this adapter's
+      // request, not a deployment without the capability. Answering it with
+      // the client-side path would produce plausible numbers and bury the
+      // contract violation, the misdirection framework#3878 documented.
+      if (failure.kind === 'rejected') {
+        throw new AnalyticsQueryRejectedError(failure.message, failure.code);
+      }
 
-      return this.aggregateClientSide(records, params);
+      // The capability is absent (404 — framework#4019 stops mounting the
+      // routes when no analytics service is registered — or 501). Say so ONCE
+      // so an operator sees a missing capability rather than charts that
+      // quietly read from a slower path forever.
+      if (failure.kind === 'not-installed') {
+        this.warnAnalyticsCapabilityOnce(failure.message);
+      }
+
+      // Degrade to find() + client-side aggregation. `aggregateViaFind`
+      // forwards the same filter, so the fallback aggregates over the SAME row
+      // set the server-side query would have — and `find()` is server-scoped,
+      // so RLS still applies.
+      return await this.aggregateViaFind(resource, params);
     }
   }
 
+  /**
+   * Client-side aggregation over a server-scoped `find()` — the fallback used
+   * whenever the analytics endpoint cannot answer (capability absent, network
+   * failure, or a result whose measure came back missing).
+   *
+   * Forwarding `params.filter` is load-bearing: without it the fallback
+   * aggregates the whole table while the caller believes it applied a filter,
+   * which is the "KPI silently sums everything" failure this adapter has
+   * guarded against since the widget filter was threaded through.
+   */
+  private async aggregateViaFind(resource: string, params: any): Promise<any[]> {
+    const result = await this.find(
+      resource as any,
+      params.filter ? ({ $filter: params.filter } as any) : undefined,
+    );
+    const records = result.data || [];
+    if (records.length === 0) return [];
+    return this.aggregateClientSide(records, params);
+  }
+
+  /**
+   * Say "the analytics capability isn't installed" ONCE per adapter, not once
+   * per widget: a dashboard fans out one aggregate() per KPI, and N identical
+   * console lines read like N different failures.
+   */
+  private warnAnalyticsCapabilityOnce(detail?: string): void {
+    if (this.analyticsCapabilityWarned) return;
+    this.analyticsCapabilityWarned = true;
+    console.warn(
+      '[OBJECTSTACKDataSource] analytics capability unavailable — aggregating client-side ' +
+      'from a scoped find(). Numbers stay correct but the semantic layer (cubes, joins, ' +
+      'server-side rollups) is off. Install @objectstack/service-analytics to enable it.' +
+      (detail ? ` Server said: ${detail}` : ''),
+    );
+  }
+
   /**
    * Run a semantic-layer `dataset` (ADR-0021) and return chart-ready rows.
    *
@@ -2411,6 +3154,16 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         const errBody = await res.json();
         detail = errBody?.message || errBody?.error || JSON.stringify(errBody);
       } catch { /* non-JSON error body */ }
+      // "The capability isn't installed" is not a stack trace to show an
+      // author (framework#3891): the REST dataset route answers 501
+      // NOT_IMPLEMENTED when no analytics service provides `queryDataset`, and
+      // a host that doesn't mount the route at all answers 404. Both mean the
+      // same thing and both get a message a UI can render verbatim; anything
+      // else (a compile error like "relationship not declared in include") is
+      // a real authoring error and keeps its server detail.
+      if (res.status === 501 || res.status === 404) {
+        throw new AnalyticsNotInstalledError('POST /analytics/dataset/query', detail || undefined);
+      }
       throw new Error(`Dataset query failed: ${res.status} ${res.statusText}${detail ? ` — ${detail}` : ''}`);
     }
 
@@ -2438,8 +3191,19 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
   }
 
   /** Client-side aggregation fallback */
-  private aggregateClientSide(records: any[], params: { field: string; function: string; groupBy: string }): any[] {
+  /**
+   * The result column an object-bound `aggregate` projects its value under
+   * (framework#3701, `chartAggregateValueKey` in `@objectstack/spec/ui`): the
+   * raw `field` name — no `sum_`-style decoration, unlike a dataset measure —
+   * or the literal `count` when a count names no field.
+   */
+  private aggregateValueKey(params: { field?: string; function?: string }): string {
+    return params.field || params.function || 'count';
+  }
+
+  private aggregateClientSide(records: any[], params: { field?: string; function: string; groupBy: string }): any[] {
     const { field, function: aggFn, groupBy } = params;
+    const valueKey = this.aggregateValueKey(params);
     const groups: Record<string, any[]> = {};
 
     for (const record of records) {
@@ -2449,7 +3213,7 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     }
 
     return Object.entries(groups).map(([key, group]) => {
-      const values = group.map(r => Number(r[field]) || 0);
+      const values = field ? group.map(r => Number(r[field]) || 0) : [];
       let result: number;
 
       switch (aggFn) {
@@ -2460,7 +3224,7 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         case 'sum': default: result = values.reduce((a, b) => a + b, 0); break;
       }
 
-      return { [groupBy]: key, [field]: result };
+      return { [groupBy]: key, [valueKey]: result };
     });
   }