@object-ui/data-objectstack 17.6.0 → 17.7.0

package/dist/index.js

@@ -4,6 +4,71 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 
 // src/index.ts
 import { ObjectStackClient } from "@objectstack/client";
+import { VIEW_CONSOLE_ROUND_TRIP_KEYS } from "@objectstack/spec/ui";
+import { DroppedFieldsEventSchema } from "@objectstack/spec/data";
+import { isFilterAST, parseFilterAST } from "@objectstack/spec/data";
+import { isRefusedTextComparand as isRefusedTextComparand2, textComparandRefusalReason as textComparandRefusalReason2 } from "@objectstack/spec/data";
+import { stripReadDecorations as stripReadDecorations2 } from "@objectstack/spec/kernel";
+
+// src/metadata-client.ts
+import { GetMetaItemLayeredResponseSchema } from "@objectstack/spec/api";
+
+// src/object-metadata-write-guard.ts
+var RELATIONSHIP_TYPES_REQUIRING_REFERENCE = ["lookup", "master_detail"];
+var CHOICE_TYPES_REQUIRING_OPTIONS = ["select", "radio"];
+var OBJECT_METADATA_TYPE = "object";
+function isUsableTarget(reference) {
+  return typeof reference === "string" && reference.trim() !== "";
+}
+function describeTarget(reference) {
+  if (reference === void 0) return "no `reference` key at all";
+  if (reference === null) return "a `null` `reference`";
+  if (typeof reference !== "string") return `a \`reference\` of type \`${typeof reference}\``;
+  if (reference === "") return "an empty `reference`";
+  return "a whitespace-only `reference`";
+}
+function hasOptionSource(def) {
+  return Array.isArray(def.options) && def.options.length > 0 || typeof def.picklist === "string";
+}
+function describeOptions(options) {
+  if (options === void 0) return "no `options` key and no `picklist`";
+  if (Array.isArray(options)) return "an empty `options` list and no `picklist`";
+  if (options === null) return "a `null` `options` and no `picklist`";
+  return `an \`options\` value of type \`${typeof options}\` and no \`picklist\``;
+}
+function fieldEntries(fields) {
+  if (Array.isArray(fields)) {
+    return fields.flatMap((raw, index) => {
+      if (!raw || typeof raw !== "object") return [];
+      const record = raw;
+      const name = typeof record.name === "string" && record.name ? record.name : `[${index}]`;
+      return [{ name, def: record }];
+    });
+  }
+  if (fields && typeof fields === "object") {
+    return Object.entries(fields).flatMap(
+      ([name, def]) => def && typeof def === "object" ? [{ name, def }] : []
+    );
+  }
+  return [];
+}
+function assertObjectMetadataWritable(type, item, writer) {
+  if (String(type) !== OBJECT_METADATA_TYPE) return;
+  if (!item || typeof item !== "object") return;
+  const fields = item.fields;
+  for (const { name, def } of fieldEntries(fields)) {
+    if (CHOICE_TYPES_REQUIRING_OPTIONS.includes(String(def.type)) && !hasOptionSource(def)) {
+      throw new Error(
+        `${writer} refused this object metadata write: the field \`${name}\` is a \`${String(def.type)}\` with no options: it carries ${describeOptions(def.options)}, so it offers nothing to choose and nothing to check a stored value against. A choice field needs at least one option or a shared \`picklist\` (objectstack#20827), so this draft stays here until it has one. Add an option, or change the field to a non-choice type.`
+      );
+    }
+    if (!RELATIONSHIP_TYPES_REQUIRING_REFERENCE.includes(String(def.type))) continue;
+    if (isUsableTarget(def.reference)) continue;
+    throw new Error(
+      `${writer} refused this object metadata write: the field \`${name}\` is a \`${String(def.type)}\` and carries ${describeTarget(def.reference)}, so it names no object to link to. \`@objectstack/spec\` refuses the same document at the server with a 422 on \`fields.${name}.reference\`, and that refusal blocks every later save of this object for as long as the half-filled field rides along in the draft (objectui#7714). Pick the target object, or change the field to a non-relationship type.`
+    );
+  }
+}
 
 // src/metadata-client.ts
 function readSaveAdvisories(body) {
@@ -16,6 +81,25 @@ function readSaveAdvisories(body) {
     return typeof c.rule === "string" && typeof c.path === "string" && typeof c.where === "string" && typeof c.message === "string" && typeof c.hint === "string" && typeof c.severity === "string";
   });
 }
+var PROTECTION_ENVELOPE_KEYS = [
+  "overlayScope",
+  "lock",
+  "lockReason",
+  "lockSource",
+  "lockDocsUrl",
+  "provenance",
+  "packageId",
+  "packageVersion",
+  "editable",
+  "deletable",
+  "resettable"
+];
+function unrecognizedEnvelopeKeys(body) {
+  const shape = GetMetaItemLayeredResponseSchema.shape;
+  return PROTECTION_ENVELOPE_KEYS.filter(
+    (key) => body[key] !== void 0 && !shape[key].safeParse(body[key]).success
+  );
+}
 var META_PREFIX = "/meta";
 var API_PREFIX = "/api/v1";
 function buildBase(config) {
@@ -28,6 +112,16 @@ function buildBase(config) {
   }
   return `${trimmed}${scoped}`;
 }
+function packagesBaseOf(metaBase) {
+  const origin = metaBase.replace(/\/api\/v\d+(?:\/environments\/[^/]+)?\/meta$/, "").replace(/\/+$/, "");
+  return `${origin}${API_PREFIX}/packages`;
+}
+function unwrapDispatcherEnvelope(body) {
+  if (!body || typeof body !== "object") return {};
+  const root = body;
+  const data = root.data;
+  return data && typeof data === "object" && !Array.isArray(data) ? data : root;
+}
 async function parseError(res) {
   let body;
   try {
@@ -60,7 +154,7 @@ var MetadataClient = class _MetadataClient {
     __publicField(this, "headers");
     /** ADR-0037: when true, reads render the draft-overlaid world. */
     __publicField(this, "previewDrafts");
-    /** #4133 — sink for post-save advisory findings; see the config field. */
+    /** #4133 / #5026 — sink for every write door's advisory findings; see the config field. */
     __publicField(this, "onSaveAdvisory");
     this.base = buildBase(config);
     this.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
@@ -214,8 +308,20 @@ var MetadataClient = class _MetadataClient {
    * {@link get} is deliberate and long-standing (the draft envelope's identity
    * and protection carriers are part of what a draft reader inspects), so it
    * is preserved by reading the transport directly instead of going through
-   * `get()`'s unwrap. `unwrapDraftBody` (app-shell) and `unwrapViewDraft`
-   * (this package) are the shared helpers for taking the body out.
+   * `get()`'s unwrap.
+   *
+   * ⛔ Do NOT hand `.item` to a gate or a write yourself: the body this serves
+   * is DECORATED (`_draft`, then `_diagnostics` from `decorateMetadataItem`),
+   * and the spec says a served body is not a valid input to the schema that
+   * produced it until those come off. {@link extractDraftBody} is the one
+   * reader for this method's answer — it takes the presence verdict and then
+   * the strip, in that order. That function used to be copy-pasted into four
+   * views and only one copy knew the rule (objectui#8181).
+   *
+   * Its tolerant siblings exist for the OTHER client method: `unwrapDraftBody`
+   * (app-shell) and `unwrapViewDraft` (this package) read a draft that arrived
+   * through {@link get}, which already unwrapped the envelope. They split on
+   * which method feeds them, not on what they mean — all three strip.
    */
   async getDraft(type, name, options = {}) {
     return this.readItemResponse(type, name, {
@@ -223,6 +329,31 @@ var MetadataClient = class _MetadataClient {
       ...options.packageId ? { packageId: options.packageId } : {}
     });
   }
+  /**
+   * Report the runtime authoring gate's advisory findings for a write the
+   * server has ALREADY committed (#4133 for the save door, #5026 for the
+   * publish door).
+   *
+   * Everything here is best-effort by construction, and that is the whole
+   * contract: the row is committed server-side before this runs, so neither a
+   * malformed body, nor a missing key, nor a throwing sink may change what the
+   * calling method returns or whether it throws. The server emits `advisories`
+   * ONLY when non-empty, so a clean write costs one absent-key check.
+   *
+   * One helper rather than a copy per door: every door's response declares the
+   * key identically, so a second inline copy could only ever drift. The batch
+   * door (`ce986aafc`) calls it once per `published[]` element, handing it
+   * the element — the object that carries the key there — and the same
+   * best-effort contract covers that loop unchanged.
+   */
+  emitAdvisories(body, event) {
+    if (!this.onSaveAdvisory) return;
+    try {
+      const advisories = readSaveAdvisories(body);
+      if (advisories.length > 0) this.onSaveAdvisory({ ...event, advisories });
+    } catch {
+    }
+  }
   /**
    * Save (PUT) a metadata item. The framework accepts both the bare
    * item payload and the `{ item: ... }` / `{ metadata: ... }`
@@ -235,6 +366,7 @@ var MetadataClient = class _MetadataClient {
         `MetadataClient.save: name must be non-empty (type="${type}"). The PUT /meta/:type/:name route requires a name segment.`
       );
     }
+    assertObjectMetadataWritable(type, item, "MetadataClient.save");
     const params = [];
     if (options.force) params.push("force=true");
     if (options.mode === "draft") params.push("mode=draft");
@@ -253,20 +385,12 @@ var MetadataClient = class _MetadataClient {
     });
     if (!res.ok) throw await parseError(res);
     const body = await res.json();
-    if (this.onSaveAdvisory) {
-      try {
-        const advisories = readSaveAdvisories(body);
-        if (advisories.length > 0) {
-          this.onSaveAdvisory({
-            type,
-            name,
-            mode: options.mode === "draft" ? "draft" : "publish",
-            advisories
-          });
-        }
-      } catch {
-      }
-    }
+    this.emitAdvisories(body, {
+      type,
+      name,
+      door: "save",
+      mode: options.mode === "draft" ? "draft" : "publish"
+    });
     return body;
   }
   /**
@@ -280,6 +404,61 @@ var MetadataClient = class _MetadataClient {
    * the rows and reports under `seedApplied` — a data problem never fails the
    * publish, so callers should check `seedApplied?.success` and warn the user
    * rather than assume the data went live.
+   *
+   * Same door as {@link publish} (`POST /meta/:type/:name/publish`), so it
+   * reports the gate's advisories the same way (#5026).
+   *
+   * The BATCH door (`POST /packages/:id/publish-drafts`) is a different route
+   * with a method of its own — {@link publishPackageDrafts} — and it reports
+   * too. It did not when this paragraph was first written: it discarded
+   * per-draft advisories server-side, which was objectstack#9343, and that card
+   * has since landed with a ruling that each `published[]` element carries
+   * them (`ce986aafc` is the client half).
+   *
+   * What survives that change is the READING RULE, which is about this method
+   * rather than about the other route: it reads the top level of the
+   * single-item body and nothing else. A batch-shaped body arriving HERE still
+   * reports nothing, because `PublishMetaItemResponse` declares no
+   * `published[]` and a client that went looking for findings wherever they
+   * might be would be inventing a contract instead of reading one.
+   *
+   * ## Why there is no `{ success, data }` unwrapping here (`7b433197d`)
+   *
+   * This method used to unwrap a dispatcher-shaped envelope before returning,
+   * while {@link publish} — the same route, a couple of hundred lines down —
+   * did not. Two spellings of one wire contract, and nothing said which was
+   * right. The tolerance is gone because the route was MEASURED, at the
+   * producer rather than inferred from the response schema:
+   *
+   *  - The only mount of `POST /api/v1/meta/:type/:name/publish` is the REST
+   *    server's own route-manager registration, which answers
+   *    `res.json(await protocol.publishMetaItem(...))` — the protocol's object
+   *    verbatim, with no envelope branch. The project-scoped mirror
+   *    (`/api/v1/environments/:environmentId/...`) re-mounts that same handler.
+   *  - The `{ success, data }` envelope has exactly one producer, the runtime
+   *    `HttpDispatcher`, and it does not serve this route: its `/meta` domain
+   *    has no publish branch, the dispatcher's own route ledger has no row for
+   *    it, and a three-segment `/meta` path that is not `/published` terminates
+   *    in a located `routeNotFound`. So no composition — REST server, the
+   *    dispatcher-only Hono adapter, or both — puts an envelope on this body.
+   *  - `packages/spec` states the same split in the two docstrings side by
+   *    side: `PublishMetaItemResponseSchema` describes "the FULL body" this
+   *    route returns and records that the REST route hands the producer's
+   *    object to `res.json()` verbatim, while its batch sibling
+   *    `PublishPackageDraftsResponseSchema` describes a body answered
+   *    explicitly "inside the dispatcher's `{ success, data }` envelope".
+   *
+   * ⛔ So an enveloped body on THIS route is not a shape the platform emits,
+   * and unwrapping one is not a kindness: it is Commandment #0.1's lenient
+   * fallback, a second de-facto contract for a route that declares one. It
+   * also fails in the direction that hides the problem — a body that arrived
+   * enveloped is one this door did not actually serve, and unwrapping it
+   * would present that as a successful promotion.
+   *
+   * ⚠️ Sibling tolerances in this file are NOT this defect and must stay:
+   * {@link listDrafts} reads `data?.data?.drafts` because `GET /meta/_drafts`
+   * IS a dispatcher route, and `publishHealthFromResponse` unwraps because the
+   * batch door really is enveloped. The rule is per-route, not per-file.
    */
   async publishDraft(type, name) {
     const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/publish`;
@@ -290,8 +469,80 @@ var MetadataClient = class _MetadataClient {
     });
     if (!res.ok) throw await parseError(res);
     const body = await res.json().catch(() => ({}));
-    const inner = body?.data && typeof body.data === "object" ? body.data : body;
-    return inner;
+    this.emitAdvisories(body, { type, name, door: "publish", mode: "publish" });
+    return body;
+  }
+  /**
+   * Publish EVERY pending draft bound to one package — Studio's "publish whole
+   * app" door, `POST /api/v1/packages/:id/publish-drafts` (ADR-0033; the route
+   * that orders structure-before-seeds server-side and runs the ADR-0038 L3
+   * runtime probes).
+   *
+   * ## Why it is expressed here at all (`ce986aafc`)
+   *
+   * It was not, and that was the defect. Two app-shell call sites fired this
+   * route with a bare `fetch` / a page-private `apiJson`, outside the seam that
+   * covers every other metadata write — so when objectstack#9343 landed and the
+   * server began sending per-draft advisories, the author publishing a whole
+   * app was told nothing, while the SAME button's client-side capability lint
+   * still raised a toast. A door that cannot report is not a door the gate can
+   * reach, however loudly the server speaks.
+   *
+   * ## What it reports, and what it refuses to invent
+   *
+   * `PublishPackageDraftsResponseSchema` declares `advisories` on EACH
+   * `published[]` element — objectstack#9343's ruled shape, the same element
+   * type and the same omitted-when-empty discipline as the single-item door,
+   * and explicitly not a parallel top-level map. So this method emits one
+   * {@link MetadataSaveAdvisoryEvent} per advised element, each naming that
+   * element's own `type` / `name`, through the same sink, event and renderer
+   * the save and single-item publish doors use.
+   *
+   * ⛔ It renders only what the server sent where the schema says it sits:
+   *
+   * - `advisories` is read off the element, by the one shared reader, which
+   *   drops anything that is not a complete finding.
+   * - An element that does not carry the `type` and `name` the schema states as
+   *   REQUIRED is skipped rather than reported under invented identity — the
+   *   event names the item the author has to go fix, and an event that cannot
+   *   name it truthfully is worse than silence.
+   * - Nothing is derived, counted or summarised from the batch: no advisory
+   *   exists here that the server did not put in the body.
+   *
+   * ## The failure shapes stay the callers'
+   *
+   * Non-2xx throws {@link MetadataError}, like every other method. A 2xx is
+   * RETURNED unexamined — `success: false` is not a failure on this route
+   * (`outcome: 'nothing_to_publish'` answers it too, and the spec's own text
+   * says to read `outcome`, not the boolean), and the two callers have their
+   * own, different rules for the refusal and rolled-back cases. Deciding that
+   * here would change behaviour this card is not about.
+   */
+  async publishPackageDrafts(packageId) {
+    if (!packageId || !String(packageId).trim()) {
+      throw new Error(
+        "MetadataClient.publishPackageDrafts: packageId must be non-empty. The POST /packages/:id/publish-drafts route requires an id segment."
+      );
+    }
+    const url = `${packagesBaseOf(this.base)}/${encodeURIComponent(packageId)}/publish-drafts`;
+    const res = await this.fetchImpl(url, {
+      method: "POST",
+      // Both call sites this replaces sent the session cookie, and the client's
+      // own fetch adds the console's Bearer token — so the routed call carries a
+      // superset of what the bare doors carried, never less.
+      credentials: "include",
+      headers: { ...this.headers, "Content-Type": "application/json", Accept: "application/json" },
+      body: "{}"
+    });
+    if (!res.ok) throw await parseError(res);
+    const body = unwrapDispatcherEnvelope(await res.json().catch(() => ({})));
+    for (const element of Array.isArray(body.published) ? body.published : []) {
+      if (!element || typeof element !== "object") continue;
+      const { type, name } = element;
+      if (typeof type !== "string" || typeof name !== "string") continue;
+      this.emitAdvisories(element, { type, name, door: "publish", mode: "publish" });
+    }
+    return body;
   }
   /**
    * Get the 3-state layered view of a metadata item: `code` (the packaged
@@ -333,7 +584,7 @@ var MetadataClient = class _MetadataClient {
     }
     if (!res.ok) throw await parseError(res);
     const body = await res.json();
-    const hasEnvelope = body && ("code" in body || "overlay" in body || "effective" in body);
+    const hasEnvelope = typeof body === "object" && body !== null && ("code" in body || "overlay" in body || "effective" in body);
     if (!hasEnvelope) {
       return {
         code: null,
@@ -342,14 +593,34 @@ var MetadataClient = class _MetadataClient {
         effective: body
       };
     }
+    const parsed = GetMetaItemLayeredResponseSchema.safeParse(body);
+    if (parsed.success) {
+      const envelope = parsed.data;
+      return {
+        code: envelope.code ?? null,
+        overlay: envelope.overlay ?? null,
+        overlayScope: envelope.overlayScope,
+        effective: envelope.effective ?? null,
+        ...body._diagnostics ? { _diagnostics: body._diagnostics } : {},
+        lock: envelope.lock,
+        ...envelope.lockReason !== void 0 ? { lockReason: envelope.lockReason } : {},
+        ...envelope.lockSource !== void 0 ? { lockSource: envelope.lockSource } : {},
+        ...envelope.lockDocsUrl !== void 0 ? { lockDocsUrl: envelope.lockDocsUrl } : {},
+        ...envelope.provenance !== void 0 ? { provenance: envelope.provenance } : {},
+        ...envelope.packageId !== void 0 ? { packageId: envelope.packageId } : {},
+        ...envelope.packageVersion !== void 0 ? { packageVersion: envelope.packageVersion } : {},
+        editable: envelope.editable,
+        deletable: envelope.deletable,
+        resettable: envelope.resettable
+      };
+    }
+    const unrecognized = unrecognizedEnvelopeKeys(body);
     return {
       code: body.code ?? null,
       overlay: body.overlay ?? null,
       overlayScope: body.overlayScope ?? null,
       effective: body.effective ?? null,
       ...body._diagnostics ? { _diagnostics: body._diagnostics } : {},
-      // ADR-0010 Phase 4 — pass through the metadata-protection envelope so
-      // the editor can render lock affordances without a second round trip.
       ...body.lock !== void 0 ? { lock: body.lock } : {},
       ...body.lockReason !== void 0 ? { lockReason: body.lockReason } : {},
       ...body.lockSource !== void 0 ? { lockSource: body.lockSource } : {},
@@ -359,7 +630,8 @@ var MetadataClient = class _MetadataClient {
       ...body.packageVersion !== void 0 ? { packageVersion: body.packageVersion } : {},
       ...body.editable !== void 0 ? { editable: body.editable } : {},
       ...body.deletable !== void 0 ? { deletable: body.deletable } : {},
-      ...body.resettable !== void 0 ? { resettable: body.resettable } : {}
+      ...body.resettable !== void 0 ? { resettable: body.resettable } : {},
+      ...unrecognized.length > 0 ? { _unrecognized: unrecognized } : {}
     };
   }
   /**
@@ -426,9 +698,16 @@ var MetadataClient = class _MetadataClient {
    * `{ success, version, seq, message }`. Throws a `404 no_draft` if
    * nothing is pending and `409 metadata_conflict` if the published
    * overlay moved while the draft was sitting.
+   *
+   * Reports the runtime authoring gate's advisory findings through
+   * {@link MetadataClientConfig.onSaveAdvisory} when the response carries them
+   * (#5026 / objectstack#9176), with `door: 'publish'`. This is the door the
+   * Studio designer takes on every edit, so it is the one whose findings an
+   * author actually sees.
    */
   async publish(type, name, options = {}) {
-    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/publish`;
+    const qs = options.packageId ? `?package=${encodeURIComponent(options.packageId)}` : "";
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/publish${qs}`;
     const headers = {
       ...this.headers,
       "Content-Type": "application/json"
@@ -439,7 +718,9 @@ var MetadataClient = class _MetadataClient {
       body: JSON.stringify(options.message ? { message: options.message } : {})
     });
     if (!res.ok) throw await parseError(res);
-    return await res.json();
+    const body = await res.json();
+    this.emitAdvisories(body, { type, name, door: "publish", mode: "publish" });
+    return body;
   }
   /**
    * Restore an item to a previous version (POST `/meta/:type/:name/rollback`).
@@ -534,15 +815,38 @@ function errorCodeIsAnyOf(err, codes) {
 }
 
 // ../core/src/utils/filter-converter.ts
-import { normalizeFilterOperator } from "@objectstack/spec/ui";
+import {
+  normalizeFilterOperator,
+  VIEW_FILTER_OPERATORS,
+  VIEW_FILTER_LIST_VALUE_OPERATORS,
+  VIEW_FILTER_PAIR_VALUE_OPERATORS
+} from "@objectstack/spec/ui";
+import { isAcceptedFilterComparand, ACCEPTED_FILTER_COMPARAND_TYPES_SENTENCE } from "@objectstack/spec/data";
+
+// ../core/src/utils/text-comparand.ts
+import { isRefusedTextComparand, textComparandRefusalReason } from "@objectstack/spec/data";
+
+// ../core/src/utils/filter-converter.ts
 var FilterOperatorError = class extends Error {
-  constructor(message) {
+  constructor(message, subject) {
     super(message);
     __publicField(this, "code", "INVALID_FILTER");
     __publicField(this, "httpStatus", 400);
+    /** @see FilterRefusalSubject */
+    __publicField(this, "operator");
+    /** @see FilterRefusalSubject */
+    __publicField(this, "field");
     this.name = "FilterOperatorError";
+    this.operator = subject?.operator;
+    this.field = subject?.field;
   }
 };
+var RETIRED_OPERATOR_ALIASES = {
+  "$notin": "$nin",
+  "$notcontains": "$notContains",
+  "$startswith": "$startsWith",
+  "$endswith": "$endsWith"
+};
 function convertOperatorToAST(operator) {
   const operatorMap = {
     "$eq": "=",
@@ -553,27 +857,148 @@ function convertOperatorToAST(operator) {
     "$lte": "<=",
     "$in": "in",
     "$nin": "nin",
-    "$notin": "nin",
     "$between": "between",
     "$contains": "contains",
     "$notContains": "notcontains",
-    "$notcontains": "notcontains",
     "$startsWith": "startswith",
-    "$startswith": "startswith",
     "$endsWith": "endswith",
-    "$endswith": "endswith"
+    // Case-insensitive contains. A canonical `FILTER_OPERATORS` member that
+    // `ValueDataSource` executes and `FilterConditionField` emits (for its
+    // `icontains` builder row — spelled `containsCaseInsensitive` until
+    // objectui#9306), while this map refused it with the
+    // generic unknown-operator paragraph — so ONE authored filter selected rows
+    // through the in-memory matcher and 400'd on the ObjectStack lowering path
+    // (objectui#8976). The other direction of the same split objectui#8568 fixed:
+    // there the map was MORE tolerant than the matcher, here it was LESS tolerant
+    // than the contract. Restored by aligning the map with the spec, per AGENTS.md
+    // #0 — not by removing the operator from the builder, which the spec declares.
+    //
+    // The VALUE is an IDENTITY, and that is not a typo: `icontains` is itself a
+    // member of the spec's `VALID_AST_OPERATORS`, so unlike its camelCase siblings
+    // above there is no case to squash. Same identity row, for the same stated
+    // reason, that `FILTER_OPERATOR_ALIASES` carries in
+    // `packages/data-objectstack/src/index.ts`.
+    "$icontains": "icontains"
   };
   return operatorMap[operator] || null;
 }
+var AST_LOGIC_KEYWORD = {
+  $and: "and",
+  $or: "or"
+};
+function lowerLogicalGroup(field, keyword, value) {
+  if (!Array.isArray(value)) {
+    throw new FilterOperatorError(
+      `[ObjectUI] The '${field}' filter combinator takes an ARRAY of conditions. Received ${typeof value === "object" ? "an object" : typeof value}: ${JSON.stringify(value)}. Spec: FilterCondition declares '${field}?: FilterCondition[]' (data/filter.zod.ts).`,
+      { operator: field }
+    );
+  }
+  if (value.length === 0) {
+    return keyword === "and" ? void 0 : falseIdentityLeaf(field, value);
+  }
+  const children = [];
+  let absorbed = false;
+  for (const child of value) {
+    if (child === null || typeof child !== "object" || Array.isArray(child)) {
+      throw new FilterOperatorError(
+        `[ObjectUI] Every member of '${field}' must be a filter condition OBJECT. Received ${JSON.stringify(child)}. Spec: FilterCondition declares '${field}?: FilterCondition[]' (data/filter.zod.ts).`,
+        { operator: field }
+      );
+    }
+    const lowered = convertFiltersToAST(child);
+    if (!Array.isArray(lowered)) {
+      if (keyword === "or") absorbed = true;
+      continue;
+    }
+    children.push(lowered);
+  }
+  if (absorbed) return void 0;
+  if (children.length === 0) return void 0;
+  return [keyword, ...children];
+}
+function falseIdentityLeaf(field, value) {
+  return [field, "=", value];
+}
+function isOperatorMap(value) {
+  const proto = Object.getPrototypeOf(value);
+  return proto === null || proto === Object.prototype || Object.getPrototypeOf(proto) === null;
+}
+function describeExoticComparand(value) {
+  let name;
+  let text2;
+  try {
+    const proto = Object.getPrototypeOf(value);
+    name = proto?.constructor?.name;
+  } catch {
+    name = void 0;
+  }
+  if (typeof name !== "string" || name === "") return "an object of an unrecognised type";
+  try {
+    text2 = String(value);
+  } catch {
+    text2 = void 0;
+  }
+  return text2 && text2 !== `[object ${name}]` ? `a ${name} instance (${text2})` : `a ${name} instance`;
+}
+function refuseTextComparand(field, operator, target) {
+  const ported = `It is refused here rather than lowered onto the wire (objectui#9001; ported from ValueDataSource's refuseTextComparand, objectui#8748).`;
+  throw new FilterOperatorError(
+    `[ObjectUI] The ${textComparandRefusalReason(field, operator, target)}. ${ported}`,
+    { operator, field }
+  );
+}
+function refuseEmptyOperatorMap(field) {
+  throw new FilterOperatorError(
+    `[ObjectUI] The filter on field '${field}' is an EMPTY operator map \u2014 { ${field}: {} } names the field and no operator. It cannot be lowered: the ObjectQL filter AST has no node for a field with zero operators, and '@objectstack/spec' ruled the shape REJECTED wherever it appears (objectstack#5240, recorded on FilterConditionSchema). It is refused here rather than dropped: beside a key that lowers, the '${field}' condition used to vanish from the filter and silently WIDEN the result set (objectui#10788), and alone it was handed back as the caller's object, which reached the wire as ?${field}=[object Object] on one route and as a filter the server refuses on the other (objectui#9164). Choose an operator \u2014 { ${field}: { $eq: ... } }, { ${field}: { $in: [...] } }, { ${field}: { $null: true } } \u2014 or remove the key.`,
+    { field }
+  );
+}
 function convertFiltersToAST(filter) {
   const conditions = [];
+  let trueIdentityGroups = 0;
+  let skippedNullKeys = 0;
   for (const [field, value] of Object.entries(filter)) {
-    if (value === null || value === void 0) continue;
+    if (value === null || value === void 0) {
+      skippedNullKeys += 1;
+      continue;
+    }
+    const logicKeyword = AST_LOGIC_KEYWORD[field];
+    if (logicKeyword) {
+      const group = lowerLogicalGroup(field, logicKeyword, value);
+      if (group !== void 0) conditions.push(group);
+      else trueIdentityGroups += 1;
+      continue;
+    }
+    if (field === "$not") {
+      throw new FilterOperatorError(
+        `[ObjectUI] The '$not' filter combinator cannot be lowered to the ObjectQL filter AST. '@objectstack/spec' declares it on FilterCondition, but the AST this layer emits has no negation keyword (FILTER_ARRAY_LOGIC_KEYWORDS is ['and', 'or']), and rewriting the negation inward is not available either \u2014 'startswith', 'endswith', 'between' and 'icontains' have no negated counterpart in VALID_AST_OPERATORS, so the rewrite would be silently partial. Express the negation with a negated operator instead ($ne, $nin, $notContains); note those follow each operator's own answer for a missing value rather than $not's NULL-safe rule (objectstack#5146). Value: ${JSON.stringify(value)}.`,
+        { operator: "$not" }
+      );
+    }
+    if (Array.isArray(value)) {
+      throw new FilterOperatorError(
+        `[ObjectUI] The filter on field '${field}' carries a bare ARRAY as its equality comparand: ${JSON.stringify(value)}. It cannot be lowered: the ObjectQL filter AST has no array-equality node, so the lowered node [${field}, '=', [...]] is refused by @objectstack/driver-sql (400 INVALID_FILTER) and matches no row in the in-memory matchers \u2014 it can never select anything. It is deliberately NOT read as membership here: { ${field}: [...] } and { ${field}: { $in: [...] } } are different statements, and guessing the second from the first would silently change which rows a stored view returns (objectui#8530; the same ruling objectui#8514 applied one layer down). Spell membership as { ${field}: { $in: [...] } }, its negation as { ${field}: { $nin: [...] } }, or a range as { ${field}: { $between: [min, max] } }.`,
+        { field }
+      );
+    }
     if (typeof value === "object" && !Array.isArray(value)) {
-      for (const [operator, operatorValue] of Object.entries(value)) {
+      if (isAcceptedFilterComparand(value)) {
+        conditions.push([field, "=", value]);
+        continue;
+      }
+      if (!isOperatorMap(value)) {
+        throw new FilterOperatorError(
+          `[ObjectUI] The filter on field '${field}' carries ${describeExoticComparand(value)} in comparand position. '@objectstack/spec' does not accept it: a comparison value must be ${ACCEPTED_FILTER_COMPARAND_TYPES_SENTENCE} (ACCEPTED_FILTER_COMPARAND_TYPES), so isAcceptedFilterComparand is false for it and normalizeFilterComparandTypes answers 400 INVALID_FILTER \u2014 "which no driver can compare". It is not an operator map either: only a plain object can be one, so until objectui#8567 this value was read as ZERO operators and the '${field}' condition was dropped from the filter entirely, silently WIDENING the result set. Spell a text match as { ${field}: { $contains: '...' } } ($startsWith / $endsWith; a pattern itself has no operator here, see the $regex refusal), a membership test as { ${field}: { $in: [...] } }, and a date bound as { ${field}: { $gte: new Date(...) } }.`,
+          { field }
+        );
+      }
+      const operatorEntries = Object.entries(value);
+      if (operatorEntries.length === 0) refuseEmptyOperatorMap(field);
+      for (const [operator, operatorValue] of operatorEntries) {
         if (operator === "$regex") {
           throw new FilterOperatorError(
-            `[ObjectUI] The '$regex' filter operator is not supported. It used to be converted to 'contains', which matches a literal substring rather than a pattern \u2014 a different result, not a degraded one. Field: '${field}', Value: ${JSON.stringify(operatorValue)}. Use $contains, $startsWith or $endsWith.`
+            `[ObjectUI] The '$regex' filter operator is not supported. It used to be converted to 'contains', which matches a literal substring rather than a pattern \u2014 a different result, not a degraded one. Field: '${field}', Value: ${JSON.stringify(operatorValue)}. Use $contains for a case-sensitive substring, $icontains for a case-insensitive one, or $startsWith / $endsWith.`,
+            { operator: "$regex", field }
           );
         }
         if (operator === "$null") {
@@ -584,12 +1009,33 @@ function convertFiltersToAST(filter) {
           conditions.push([field, operatorValue ? "is_not_null" : "is_null", true]);
           continue;
         }
+        if (operator === "$empty") {
+          if (operatorValue !== true && operatorValue !== false) {
+            throw new FilterOperatorError(
+              `[ObjectUI] The '$empty' filter operator on field '${field}' takes a boolean flag (true or false); received ${JSON.stringify(operatorValue) ?? String(operatorValue)}. Write { ${field}: { $empty: true } } for an empty value, or { ${field}: { $empty: false } } for a non-empty one.`,
+              { operator: "$empty", field }
+            );
+          }
+          conditions.push([field, operatorValue ? "is_empty" : "is_not_empty", true]);
+          continue;
+        }
         const astOperator = convertOperatorToAST(operator);
         if (astOperator) {
+          if (astOperator === "icontains" && isRefusedTextComparand(operatorValue)) {
+            refuseTextComparand(field, operator, operatorValue);
+          }
           conditions.push([field, astOperator, operatorValue]);
         } else {
+          const canonical = RETIRED_OPERATOR_ALIASES[operator];
+          if (canonical) {
+            throw new FilterOperatorError(
+              `[ObjectUI] The '${operator}' filter operator is retired. Write '${canonical}' instead \u2014 the canonical spelling '@objectstack/spec' declares in FILTER_OPERATORS (data/filter.zod.ts). The operator itself is unchanged; only the key is renamed. Field: '${field}', Value: ${JSON.stringify(operatorValue)}. It used to be accepted here as a lowercase alias while the in-memory matcher refused it, so the same filter selected rows through one data source and none through the other (objectui#8568).`,
+              { operator, field }
+            );
+          }
           throw new FilterOperatorError(
-            `[ObjectUI] Unknown filter operator '${operator}' for field '${field}'. Supported operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $between, $contains, $notContains, $startsWith, $endsWith, $null, $exists. If you need exact object matching, use the value directly without an operator.`
+            `[ObjectUI] Unknown filter operator '${operator}' for field '${field}'. Supported operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $between, $contains, $notContains, $startsWith, $endsWith, $icontains, $null, $exists, $empty. If you need exact object matching, use the value directly without an operator.`,
+            { operator, field }
           );
         }
       }
@@ -598,6 +1044,13 @@ function convertFiltersToAST(filter) {
     }
   }
   if (conditions.length === 0) {
+    const keysTheLoopProcessed = Object.keys(filter).length - skippedNullKeys;
+    if (trueIdentityGroups > 0 && trueIdentityGroups === keysTheLoopProcessed) {
+      return void 0;
+    }
+    if (skippedNullKeys > 0 && skippedNullKeys === Object.keys(filter).length) {
+      return void 0;
+    }
     return filter;
   }
   if (conditions.length === 1) {
@@ -605,6 +1058,52 @@ function convertFiltersToAST(filter) {
   }
   return ["and", ...conditions];
 }
+var ARRAY_VALUED_VIEW_OPERATORS = /* @__PURE__ */ new Set([
+  ...VIEW_FILTER_LIST_VALUE_OPERATORS,
+  ...VIEW_FILTER_PAIR_VALUE_OPERATORS
+]);
+var KNOWN_VIEW_OPERATORS = new Set(VIEW_FILTER_OPERATORS);
+
+// ../core/src/utils/column-sortability.ts
+import {
+  FIELD_UNSORTABLE_VIRTUAL_TYPE,
+  FIELD_SORTABLE_UNPROVISIONED_ANCHOR
+} from "@objectstack/spec/api";
+var OBJECT_SORTABILITY_KEY = /* @__PURE__ */ Symbol.for("objectui.objectSortability");
+function asFieldSortability(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const sortable = value.sortable;
+  if (typeof sortable !== "boolean") return void 0;
+  const reason = value.reason;
+  const caveat = value.caveat;
+  return {
+    sortable,
+    ...typeof reason === "string" ? { reason } : {},
+    ...typeof caveat === "string" ? { caveat } : {}
+  };
+}
+function normalizeObjectSortability(served) {
+  if (!served || typeof served !== "object" || Array.isArray(served)) return void 0;
+  const rawFields = served.fields;
+  if (!rawFields || typeof rawFields !== "object" || Array.isArray(rawFields)) return void 0;
+  const fields = {};
+  for (const [name, entry] of Object.entries(rawFields)) {
+    const verdict = asFieldSortability(entry);
+    if (verdict) fields[name] = verdict;
+  }
+  return { fields };
+}
+function attachObjectSortability(schema, served) {
+  const projection = normalizeObjectSortability(served);
+  if (!projection || !schema || typeof schema !== "object") return schema;
+  Object.defineProperty(schema, OBJECT_SORTABILITY_KEY, {
+    value: projection,
+    enumerable: false,
+    configurable: true,
+    writable: true
+  });
+  return schema;
+}
 
 // ../core/src/adapters/batchTransaction.ts
 function idOf(rec) {
@@ -673,20 +1172,143 @@ async function emulateBatchTransaction(dataSource, operations) {
 }
 
 // ../core/src/utils/reference-keys.ts
-function normalizeFieldReferenceKeys(fieldDef) {
+import { FIELD_KEY_GUIDANCE, FieldSchema } from "@objectstack/spec/data";
+var aliasProbe = (key) => key.toLowerCase().replace(/[_\-\s]/g, "");
+var declaredFieldKeys = null;
+var probeFolds = null;
+var collidingProbes = null;
+function fieldKeyFolds() {
+  if (probeFolds) return probeFolds;
+  const declared = Object.keys(FieldSchema.shape);
+  const seen = /* @__PURE__ */ new Map();
+  for (const key of declared) {
+    const probe = aliasProbe(key);
+    seen.set(probe, [...seen.get(probe) ?? [], key]);
+  }
+  const folds = /* @__PURE__ */ new Map();
+  const collisions = /* @__PURE__ */ new Map();
+  for (const [probe, keys] of seen) {
+    if (keys.length === 1) folds.set(probe, keys[0]);
+    else collisions.set(probe, keys);
+  }
+  declaredFieldKeys = new Set(declared);
+  collidingProbes = collisions;
+  probeFolds = folds;
+  return folds;
+}
+var warnedRetiredSpelling = /* @__PURE__ */ new Set();
+var warnedUnfoldableSpelling = /* @__PURE__ */ new Set();
+function warnUnfoldableRetiredKey(reason, key, detail, fieldName, objectName, f) {
+  if (!isDev()) return;
+  const named = fieldName ?? (typeof f.name === "string" ? f.name : "(unnamed field)");
+  const owner = objectName ?? "(unknown object)";
+  const memo = `${owner}:${named}:${key}:${reason}`;
+  if (warnedUnfoldableSpelling.has(memo)) return;
+  const published = reason === "no-declared-twin" && key === "id_field" ? ` \`@objectstack/spec\`'s \`FIELD_KEY_GUIDANCE\` gives the reason: ${FIELD_KEY_GUIDANCE.id_field.why}` : "";
+  warnedUnfoldableSpelling.add(memo);
+  console.warn(
+    `[ObjectUI] Object \`${owner}\`, field \`${named}\`: the ingestion choke point CANNOT canonicalize the retired spelling \`${key}\`. ${detail}${published} The key and its value are LEFT on the def exactly as served \u2014 nothing is dropped here \u2014 but a consumer that reads only the spellings \`@objectstack/spec\`'s \`FieldSchema\` declares will not see this value. Fix the PRODUCER, or migrate the stored document. (maintainer ruling item 3 on objectui#7650; objectui#8938)`
+  );
+}
+function canonicalizeRetiredFieldKeys(f, fieldName, objectName) {
+  const folds = fieldKeyFolds();
+  for (const key of Object.keys(f)) {
+    if (declaredFieldKeys.has(key)) continue;
+    const value = f[key];
+    if (value === void 0) continue;
+    if (REFERENCE_ARM_KEYS.has(key)) continue;
+    const probe = aliasProbe(key);
+    const canonical = folds.get(probe);
+    if (canonical === void 0) {
+      const colliding = collidingProbes.get(probe);
+      if (colliding) {
+        warnUnfoldableRetiredKey(
+          "ambiguous-probe",
+          key,
+          `Its alias spelling is shared by MORE THAN ONE key \`FieldSchema\` declares (${colliding.map((c) => `\`${c}\``).join(", ")}), so the fold refuses to choose between them rather than picking one.`,
+          fieldName,
+          objectName,
+          f
+        );
+      } else {
+        warnUnfoldableRetiredKey(
+          "no-declared-twin",
+          key,
+          `\`FieldSchema\` declares neither \`${key}\` nor any key sharing its alias spelling (lowercased, with \`_\`, \`-\` and spaces removed), so there is no canonical key to fold it onto \u2014 and this path deliberately does not guess a near match.`,
+          fieldName,
+          objectName,
+          f
+        );
+      }
+      continue;
+    }
+    if (f[canonical] !== void 0) {
+      if (f[canonical] !== value) {
+        warnUnfoldableRetiredKey(
+          "canonical-occupied",
+          key,
+          `\`FieldSchema\` declares \`${canonical}\`, and this def already carries a DIFFERENT value under it; the producer's value stands, because this choke point never overwrites one.`,
+          fieldName,
+          objectName,
+          f
+        );
+      }
+      continue;
+    }
+    f[canonical] = value;
+    if (!isDev()) continue;
+    const named = fieldName ?? (typeof f.name === "string" ? f.name : "(unnamed field)");
+    const owner = objectName ?? "(unknown object)";
+    const memo = `${owner}:${named}:${key}:${canonical}`;
+    if (warnedRetiredSpelling.has(memo)) continue;
+    warnedRetiredSpelling.add(memo);
+    console.warn(
+      `[ObjectUI] Object \`${owner}\`, field \`${named}\` carries the retired spelling \`${key}\`. \`@objectstack/spec\`'s \`FieldSchema\` declares \`${canonical}\` and does not declare \`${key}\`, so a producer emitting it would be refused at the metadata write door. ObjectUI stamps \`${canonical}\` here so this stored def still renders, but the consumers no longer carry a \`${key}\` fallback of their own \u2014 fix the PRODUCER, or migrate the stored document. (objectui#7650)`
+    );
+  }
+}
+var warnedLegacyOnly = /* @__PURE__ */ new Set();
+var isDev = () => globalThis.process?.env?.NODE_ENV !== "production";
+var LEGACY_REFERENCE_KEYS = ["reference_to", "referenceTo"];
+var REFERENCE_ARM_KEYS = new Set(LEGACY_REFERENCE_KEYS);
+function warnOnLegacyOnlyReference(f, fieldName, objectName) {
+  if (!isDev()) return;
+  if (f.reference !== void 0) return;
+  const spelled = LEGACY_REFERENCE_KEYS.filter((k) => f[k] !== void 0 && f[k] !== "");
+  if (spelled.length === 0) return;
+  const named = fieldName ?? (typeof f.name === "string" ? f.name : "(unnamed field)");
+  const owner = objectName ?? "(unknown object)";
+  for (const key of spelled) {
+    const memo = `${owner}:${named}:${key}:${String(f[key])}`;
+    if (warnedLegacyOnly.has(memo)) continue;
+    warnedLegacyOnly.add(memo);
+    console.warn(
+      `[ObjectUI] Object \`${owner}\`, field \`${named}\` declares its relationship target as \`${key}: '${String(f[key])}'\` and does NOT carry \`reference\`. \`reference\` is the only spelling the protocol declares: \`@objectstack/spec\`'s \`FieldSchema\` refuses \`${key}\` by name with \`unrecognized_keys\` ("Did you mean \`${key}\` -> \`reference\`?"). ObjectUI stamps \`reference\` here so this def still renders, but the readers no longer carry a \`${key}\` fallback of their own \u2014 fix the PRODUCER to emit \`reference\`, or serve the def through a backend that normalizes it (objectstack#13847 does this on the serve path and in \`os migrate meta\`). Maintainer ruling 2026-08-31: protocol normalization belongs on the server, the front end just executes the protocol. (objectui#6837)`
+    );
+  }
+}
+function normalizeFieldReferenceKeys(fieldDef, fieldName, objectName) {
   if (!fieldDef || typeof fieldDef !== "object") return fieldDef;
   const f = fieldDef;
-  const target = f.reference_to ?? f.reference ?? f.referenceTo;
-  if (target == null || target === "") return fieldDef;
-  if (f.reference_to === void 0) f.reference_to = target;
-  if (f.reference === void 0) f.reference = target;
+  canonicalizeRetiredFieldKeys(f, fieldName, objectName);
+  if (f.reference !== void 0) return fieldDef;
+  const legacy = f.reference_to ?? f.referenceTo;
+  if (legacy == null || legacy === "") return fieldDef;
+  warnOnLegacyOnlyReference(f, fieldName, objectName);
+  f.reference = legacy;
   return fieldDef;
 }
 function normalizeSchemaReferenceKeys(schema) {
   const fields = schema && typeof schema === "object" ? schema.fields : null;
   if (!fields || typeof fields !== "object") return schema;
-  const defs = Array.isArray(fields) ? fields : Object.values(fields);
-  for (const def of defs) normalizeFieldReferenceKeys(def);
+  const objectName = typeof schema.name === "string" ? schema.name : void 0;
+  if (Array.isArray(fields)) {
+    for (const def of fields) normalizeFieldReferenceKeys(def, void 0, objectName);
+  } else {
+    for (const [name, def] of Object.entries(fields)) {
+      normalizeFieldReferenceKeys(def, name, objectName);
+    }
+  }
   return schema;
 }
 
@@ -1059,6 +1681,25 @@ function isErrorType(error, errorClass) {
   return error instanceof errorClass;
 }
 
+// src/error-envelope.ts
+function readErrorEnvelope(body) {
+  if (!body || typeof body !== "object") return {};
+  const env = body;
+  const nested = env.error && typeof env.error === "object" ? env.error : void 0;
+  const reading = {};
+  const message = text(nested?.message) ?? text(env.message) ?? text(env.error);
+  if (message !== void 0) reading.message = message;
+  const code = present(env.code) ?? present(nested?.code);
+  if (code !== void 0) reading.code = code;
+  return reading;
+}
+function text(value) {
+  return typeof value === "string" && value.trim() !== "" ? value : void 0;
+}
+function present(value) {
+  return typeof value === "string" ? value : void 0;
+}
+
 // src/userState.ts
 var DEFAULT_RESOURCE = "sys_user_preference";
 function createObjectStackUserStateAdapter(options) {
@@ -1161,6 +1802,33 @@ function createObjectStackUserStateAdapter(options) {
   };
 }
 
+// src/draft-envelope.ts
+import { stripReadDecorations } from "@objectstack/spec/kernel";
+function extractDraftBody(resp) {
+  if (!resp || typeof resp !== "object") return null;
+  const env = resp;
+  if (!("item" in env)) return null;
+  const body = env.item;
+  if (!body || typeof body !== "object") return null;
+  if (Object.keys(body).length === 0) return null;
+  return stripReadDecorations(body);
+}
+
+// src/metadata-error.ts
+function extractIssues(e) {
+  const issues = e?.issues;
+  return Array.isArray(issues) ? issues : [];
+}
+function formatMetadataIssue(i) {
+  return `\u2022 ${i.path && i.path.length > 0 ? i.path : "(root)"} \u2014 ${i.message}`;
+}
+function formatMetadataError(e) {
+  const issues = extractIssues(e);
+  if (issues.length > 0) return issues.map(formatMetadataIssue).join("\n");
+  const err = e;
+  return err?.message ?? String(e);
+}
+
 // src/index.ts
 var FILTER_OPERATOR_ALIASES = {
   equals: "=",
@@ -1218,14 +1886,21 @@ var FILTER_OPERATOR_ALIASES = {
   before: "<",
   after: ">"
 };
-function normalizeFilterOperator2(op) {
+function toAstFilterOperator(op) {
   if (typeof op !== "string") return null;
   const lower = op.toLowerCase();
   return FILTER_OPERATOR_ALIASES[lower] ?? FILTER_OPERATOR_ALIASES[op] ?? op;
 }
+function describeFilterEntry(entry) {
+  try {
+    return JSON.stringify(entry, (_key, value) => typeof value === "bigint" ? `${value}n` : value) ?? String(entry);
+  } catch {
+    return String(entry);
+  }
+}
 var MalformedFilterError = class extends Error {
   constructor(entry, index) {
-    const shown = JSON.stringify(entry) ?? String(entry);
+    const shown = describeFilterEntry(entry);
     super(
       `Filter entry ${index} is not a usable filter rule (${shown}). Expected { field, operator, value } with a non-empty field.`
     );
@@ -1243,12 +1918,104 @@ function isMalformedFilterError(error) {
   const e = error;
   return e.code === "INVALID_FILTER" || e.name === "MalformedFilterError";
 }
-function objectFilterEntryToAST(entry) {
+var UnloweredAggregateWhereError = class extends Error {
+  constructor(where, resource) {
+    const shown = JSON.stringify(where) ?? String(where);
+    super(
+      `aggregate('${resource}'): the spec-shape branch received a \`where\` array that is not a filter \u2014 ${shown}. This branch posts \`where\` to POST /data/:object/query verbatim, so it must ALREADY be lowered: either a FilterCondition object (\`QuerySchema.where\`, @objectstack/spec data/query.zod.ts), or a FilterArray the ingress can lower \u2014 a comparison tuple (['stage','=','won']), a logical node (['and',[..],[..]]), or an array of nodes (data/filter.zod.ts, gate \`isFilterAST\`). A ViewFilterRule[] ([{ field, operator, value }, ...]) is authoring sugar, not a filter: lower it in the producer that built these aggregate params, not here. Nothing was sent to the server, so no unfiltered numbers came back.`
+    );
+    __publicField(this, "code", "INVALID_FILTER");
+    __publicField(this, "httpStatus", 400);
+    /** The value as received, so a caller can log what its producer actually built. */
+    __publicField(this, "where");
+    /** The object `aggregate()` was called for. */
+    __publicField(this, "resource");
+    this.name = "UnloweredAggregateWhereError";
+    this.where = where;
+    this.resource = resource;
+  }
+};
+function assertSpecShapeWhereIsFilterAst(where, resource) {
+  if (!Array.isArray(where)) return;
+  if (where.length === 0) return;
+  if (isFilterAST(where)) return;
+  throw new UnloweredAggregateWhereError(where, resource);
+}
+var ANALYTICS_ONLY_AGGREGATE_KEYS = ["filter", "field", "function"];
+var ANALYTICS_ONLY_KEY_ADVICE = {
+  filter: "`filter` is the ANALYTICS branch's filter and is lowered there through `parseFilterAST`; this branch's filter is `where` (`QuerySchema.where`, @objectstack/spec data/query.zod.ts) and is posted VERBATIM \u2014 rename it to `where` and lower it in the producer.",
+  field: "`field` is half of the analytics branch's `${field}_${function}` measure; this branch's measure is `aggregations`, an AggregationNode[] such as [{ function: 'sum', field: 'amount', alias: 'amount_sum' }].",
+  function: "`function` is the other half of that measure pair and belongs inside an `aggregations` node, not beside `groupBy`."
+};
+function specShapeSelectorReasons(params) {
+  const reasons = [];
+  if (Array.isArray(params?.groupBy)) reasons.push("`groupBy` is an array");
+  if (Array.isArray(params?.aggregations)) reasons.push("`aggregations` is an array");
+  if (params?.where !== void 0) reasons.push("a `where` key is present");
+  return reasons;
+}
+var AnalyticsKeysOnSpecShapeError = class extends Error {
+  constructor(keys, params, resource) {
+    const received = {};
+    for (const key of keys) received[key] = params?.[key];
+    const named = keys.map((k) => `\`${k}\``).join(", ");
+    const shown = keys.map((k) => `${k}=${JSON.stringify(params?.[k]) ?? String(params?.[k])}`).join(", ");
+    const why = specShapeSelectorReasons(params).join(" and ");
+    const noMeasure = !Array.isArray(params?.aggregations) ? " Because no `aggregations` was supplied either, the query this would have built is a grouping with NO MEASURE \u2014 the chart renders and its numbers mean nothing." : "";
+    super(
+      `aggregate('${resource}'): the spec-shape branch received the analytics branch's ${named} \u2014 ${shown} \u2014 and reads none of them. This call took the spec-shape branch because ${why}; the branch posts only \`groupBy\`, \`aggregations\`, \`where\` and \`limit\` to POST /data/:object/query, so those keys would have been dropped in silence.${noMeasure} ` + keys.map((k) => ANALYTICS_ONLY_KEY_ADVICE[k]).join(" ") + " The two shapes are alternatives, not a mixture: the analytics branch (`{ field, function, groupBy, filter }`, which lowers its filter for you) is reached only when NONE of an array `groupBy`, an array `aggregations` or a `where` key is present. Nothing was sent to the server, so no unfiltered numbers came back."
+    );
+    __publicField(this, "code", "INVALID_FILTER");
+    __publicField(this, "httpStatus", 400);
+    /** The offending keys, in the order {@link ANALYTICS_ONLY_AGGREGATE_KEYS} lists them. */
+    __publicField(this, "keys");
+    /** What each offending key carried, so a producer is identifiable from a log. */
+    __publicField(this, "received");
+    /** The object `aggregate()` was called for. */
+    __publicField(this, "resource");
+    this.name = "AnalyticsKeysOnSpecShapeError";
+    this.keys = keys;
+    this.received = received;
+    this.resource = resource;
+  }
+};
+function assertNoAnalyticsKeysOnSpecShape(params, resource) {
+  const present2 = ANALYTICS_ONLY_AGGREGATE_KEYS.filter((key) => params?.[key] != null);
+  if (present2.length === 0) return;
+  throw new AnalyticsKeysOnSpecShapeError(present2, params, resource);
+}
+var UnlowerableAnalyticsFilterError = class extends Error {
+  constructor(filter, resource, detail) {
+    const shown = JSON.stringify(filter) ?? String(filter);
+    super(
+      `aggregate('${resource}'): the analytics branch received a \`filter\` array that \`parseFilterAST\` cannot lower into a FilterCondition \u2014 ${shown}.` + (detail ? ` (${detail})` : "") + " `where` on the analytics wire is a FilterCondition (`AnalyticsQuerySchema`, @objectstack/spec data/analytics.zod.ts), and a FilterArray is input-only sugar lowered into one at the single sink `parseFilterAST` (data/filter.zod.ts, objectstack#5158 ruling C). Lowerable shapes are a comparison tuple (['stage','=','won']), a logical node (['and',[..],[..]]), an array of such nodes, and a ViewFilterRule[] this adapter translates first. An infix join ([condA, 'or', condB]) is none of them. Nothing was sent to the server, so no unfiltered numbers came back."
+    );
+    __publicField(this, "code", "INVALID_FILTER");
+    __publicField(this, "httpStatus", 400);
+    /** The filter as received, so a caller can log what its producer actually built. */
+    __publicField(this, "filter");
+    /** The object `aggregate()` was called for. */
+    __publicField(this, "resource");
+    this.name = "UnlowerableAnalyticsFilterError";
+    this.filter = filter;
+    this.resource = resource;
+  }
+};
+function refuseTextComparandEntry(entry, index, field, arrived) {
+  const tail = `This is a { field, operator, value } rule entry, so it is refused as the filter is translated rather than sent: the spelling @objectstack/spec's FILTER_TEXT_CASES uses for this operator is the $-dialect '$icontains', which this form spells '${arrived}'. Remove the entry, or give it a non-empty string value (objectui#9048; the same refusal convertFiltersToAST and ValueDataSource already share).`;
+  const error = new MalformedFilterError(entry, index);
+  error.message = `Filter entry ${index} is refused. The ${textComparandRefusalReason2(field, arrived, entry.value)}. ${tail}`;
+  throw error;
+}
+function objectFilterEntryToAST(entry, index) {
   if (!entry || typeof entry !== "object") return null;
   const field = entry.field;
   const rawOp = entry.operator ?? entry.op ?? "=";
-  const op = normalizeFilterOperator2(rawOp);
+  const op = toAstFilterOperator(rawOp);
   if (!field || !op) return null;
+  if (op === "icontains" && isRefusedTextComparand2(entry.value)) {
+    refuseTextComparandEntry(entry, index, String(field), rawOp);
+  }
   return [String(field), op, entry.value];
 }
 function isObjectFilterEntryForm(filter) {
@@ -1257,8 +2024,8 @@ function isObjectFilterEntryForm(filter) {
 }
 function objectFilterEntriesToAST(entries) {
   const nodes = entries.map((entry, i) => {
-    if (Array.isArray(entry)) return translateFilterChild(entry);
-    const tuple = objectFilterEntryToAST(entry);
+    if (Array.isArray(entry)) return translateFilterChild(entry, i);
+    const tuple = objectFilterEntryToAST(entry, i);
     if (!tuple) throw new MalformedFilterError(entry, i);
     return tuple;
   });
@@ -1269,15 +2036,17 @@ function translateFilterArray(filter) {
   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)];
+    return [head, ...filter.slice(1).map((child, i) => translateFilterChild(child, i + 1))];
+  }
+  if (filter.every((child) => Array.isArray(child))) {
+    return filter.map((child, i) => translateFilterChild(child, i));
   }
-  if (filter.every((child) => Array.isArray(child))) return filter.map(translateFilterChild);
   return filter;
 }
-function translateFilterChild(child) {
+function translateFilterChild(child, index) {
   if (Array.isArray(child)) return child.length > 0 ? translateFilterArray(child) : child;
   if (child && typeof child === "object" && child.field !== void 0) {
-    const tuple = objectFilterEntryToAST(child);
+    const tuple = objectFilterEntryToAST(child, index);
     if (tuple) return tuple;
   }
   return child;
@@ -1294,6 +2063,30 @@ function translateFilterToAST(filter) {
   }
   return void 0;
 }
+function lowerAnalyticsFilterForWire(filter, resource) {
+  if (!Array.isArray(filter)) return filter;
+  if (filter.length === 0) return void 0;
+  const ast = translateFilterArray(filter);
+  if (!isFilterAST(ast)) throw new UnlowerableAnalyticsFilterError(filter, resource);
+  let lowered;
+  try {
+    lowered = parseFilterAST(ast);
+  } catch (e) {
+    throw new UnlowerableAnalyticsFilterError(
+      filter,
+      resource,
+      e instanceof Error ? e.message : String(e)
+    );
+  }
+  if (lowered === void 0) {
+    throw new UnlowerableAnalyticsFilterError(
+      filter,
+      resource,
+      "`parseFilterAST` answered `undefined` for a non-empty filter"
+    );
+  }
+  return lowered;
+}
 function serializeOrderBy(orderby) {
   if (orderby === void 0 || orderby === null) return void 0;
   if (typeof orderby === "string") {
@@ -1356,6 +2149,37 @@ var APP_PERMISSION_DENIED_CODE = "PERMISSION_DENIED";
 function isAppPermissionDeniedError(error) {
   return errorCodeIs(error, APP_PERMISSION_DENIED_CODE);
 }
+var META_ITEM_ABSENT_CODE = "RESOURCE_NOT_FOUND";
+function isMetaItemAbsentError(error) {
+  return errorCodeIs(error, META_ITEM_ABSENT_CODE);
+}
+function metaEnvelopeCarriesItem(envelope) {
+  if (envelope == null || typeof envelope !== "object") return false;
+  return envelope.item != null;
+}
+var VIEW_CONFIG_CAPABILITY = "manage_metadata";
+var ViewConfigPermissionDeniedError = class extends Error {
+  constructor(objectName, viewId) {
+    super(
+      `View configuration is shared: changing "${viewId}" changes it for everyone who uses this view. That requires the "${VIEW_CONFIG_CAPABILITY}" capability, which this session does not hold.`
+    );
+    __publicField(this, "code", "VIEW_CONFIG_PERMISSION_DENIED");
+    /** The capability that was required and not held. */
+    __publicField(this, "capability", VIEW_CONFIG_CAPABILITY);
+    /** The object whose view configuration the refused write targeted. */
+    __publicField(this, "objectName");
+    /** The view id the refused write targeted. */
+    __publicField(this, "viewId");
+    this.name = "ViewConfigPermissionDeniedError";
+    this.objectName = objectName;
+    this.viewId = viewId;
+  }
+};
+function isViewConfigPermissionDeniedError(error) {
+  if (!error || typeof error !== "object") return false;
+  const e = error;
+  return e.code === "VIEW_CONFIG_PERMISSION_DENIED" || e.name === "ViewConfigPermissionDeniedError";
+}
 var AnalyticsNotInstalledError = class extends Error {
   constructor(surface, detail, serverCode) {
     super(
@@ -1424,6 +2248,25 @@ var AnalyticsUnauthenticatedError = class extends Error {
     this.serverMessage = opts.serverMessage;
   }
 };
+var AnalyticsForbiddenError = class extends Error {
+  constructor(opts = {}) {
+    super(
+      `Analytics query refused: this user may not read the data behind ${opts.datasetName ? `dataset "${opts.datasetName}"` : "this dataset"}.` + (opts.serverMessage ? ` (server said: ${opts.serverMessage})` : "")
+    );
+    __publicField(this, "code", "PERMISSION_DENIED");
+    __publicField(this, "httpStatus", 403);
+    /** The server's own ADR-0112 code — the field this branch was chosen BY. */
+    __publicField(this, "serverCode");
+    /** The server's own message, verbatim (diagnostics only). */
+    __publicField(this, "serverMessage");
+    /** The dataset the refused query asked for, when it named one. */
+    __publicField(this, "datasetName");
+    this.name = "AnalyticsForbiddenError";
+    this.serverCode = opts.serverCode;
+    this.serverMessage = opts.serverMessage;
+    this.datasetName = opts.datasetName;
+  }
+};
 function readAnalyticsErrorEnvelope(body) {
   if (!body || typeof body !== "object") return {};
   const flat = body;
@@ -1446,6 +2289,30 @@ var AnalyticsQueryRejectedError = class extends Error {
     this.serverCode = serverCode;
   }
 };
+var AnalyticsResultShapeError = class extends Error {
+  constructor(resource, result) {
+    const value = result;
+    const envelope = Array.isArray(value?.data?.rows);
+    const received = result === null ? "null" : Array.isArray(result) ? "an array" : typeof result !== "object" ? typeof result : `an object with keys [${Object.keys(result).join(", ")}]`;
+    super(
+      envelope ? `aggregate('${resource}'): client.analytics.query resolved to the \`{ data: { rows } }\` envelope, not to an AnalyticsResult. @objectstack/client resolves this method to the payload itself since 17.3.0 (objectstack#13079), and this adapter reads \`rows\` only: an older client is installed beside it, or something between the client and POST /analytics/query wraps the payload a second time. Install @objectstack/client 17.3.0 or later.` : `aggregate('${resource}'): client.analytics.query resolved to ${received}, which has no \`rows\` array, so it is not an AnalyticsResult. This adapter reads \`rows\` only (objectui#7028).`
+    );
+    __publicField(this, "code", "ANALYTICS_RESULT_SHAPE_INVALID");
+    /** The object `aggregate()` was called for. */
+    __publicField(this, "resource");
+    /**
+     * True when the value is the envelope the client stopped handing back at
+     * 17.3.0 — `{ success, data: { rows } }`, or its `{ data: { rows } }` core.
+     */
+    __publicField(this, "envelope");
+    /** What the value was, so the producer is identifiable from a log. */
+    __publicField(this, "received");
+    this.name = "AnalyticsResultShapeError";
+    this.resource = resource;
+    this.envelope = envelope;
+    this.received = received;
+  }
+};
 function classifyAnalyticsFailure(error) {
   const err = error ?? {};
   const code = typeof err.code === "string" && err.code.length > 0 ? err.code : void 0;
@@ -1457,11 +2324,11 @@ function classifyAnalyticsFailure(error) {
   if (errorCodeIs({ code }, "VALIDATION_FAILED")) return { kind: "rejected", code, message };
   if (errorCodeIs({ code }, "UNAUTHENTICATED")) return { kind: "unauthenticated", code, message };
   if (errorCodeIs({ code }, "CUBE_NOT_FOUND")) return { kind: "cube-not-found", code, message };
+  if (status === 400) return { kind: "rejected", code, message };
   if (code === void 0) {
     if (status !== void 0 && ANALYTICS_ABSENT_STATUSES.includes(status)) {
       return { kind: "not-installed", code, message };
     }
-    if (status === 400) return { kind: "rejected", code, message };
     if (status === 401) return { kind: "unauthenticated", code, message };
   }
   return { kind: "unknown", code, message };
@@ -1473,9 +2340,22 @@ var ConcurrentUpdateError = class extends Error {
     __publicField(this, "httpStatus", 409);
     __publicField(this, "currentVersion");
     __publicField(this, "currentRecord");
+    /**
+     * The refusal text the PRODUCER marked as addressed to the end user
+     * (`ApiErrorSchema.userMessage`, objectstack `79c46da90`), or `null` when the
+     * refusal carried no marking.
+     *
+     * Declared on the class because this error has no `details` bag: the shared
+     * reader (`declaredUserMessage` in `@object-ui/react`) looks at the
+     * top-level field first, so parking it here is what makes the marking
+     * readable at the surface. The contract is status-agnostic — a 409 carries
+     * it exactly like a 400 or a 403 does.
+     */
+    __publicField(this, "userMessage");
     this.name = "ConcurrentUpdateError";
     this.currentVersion = opts.currentVersion;
     this.currentRecord = opts.currentRecord;
+    this.userMessage = opts.userMessage ?? null;
   }
 };
 function isConcurrentUpdateError(error) {
@@ -1483,10 +2363,18 @@ function isConcurrentUpdateError(error) {
   const e = error;
   return e.code === "CONCURRENT_UPDATE" || e.name === "ConcurrentUpdateError";
 }
+function liftUserMessage(e, details) {
+  if (typeof e.userMessage === "string" && e.userMessage.trim()) return e.userMessage;
+  if (typeof details.userMessage === "string" && details.userMessage.trim()) {
+    return details.userMessage;
+  }
+  return null;
+}
 function normaliseClientError(error) {
   if (!error || typeof error !== "object") return error;
   const e = error;
   const details = e.details ?? {};
+  const userMessage = liftUserMessage(e, details);
   if (e.code === "VALIDATION_FAILED" || e.name === "ValidationError") {
     const rawFields = Array.isArray(details.fields) ? details.fields : Array.isArray(e.fields) ? e.fields : [];
     const validationErrors = rawFields.map((f) => {
@@ -1500,15 +2388,21 @@ function normaliseClientError(error) {
       typeof e.message === "string" ? e.message : "Validation failed",
       validationErrors[0]?.field,
       validationErrors,
-      { fields: rawFields }
+      // The marking rides the details bag exactly the way `fields` already
+      // does, landing on `err.details.userMessage` — the second of the two
+      // places the shared reader looks. Purely additive: `field`,
+      // `validationErrors` and `fields` are untouched, so the per-field
+      // marking a form already draws keeps working. Omitted entirely when
+      // unmarked, so an unmarked refusal carries no empty key.
+      userMessage === null ? { fields: rawFields } : { fields: rawFields, userMessage }
     );
   }
-  if (e.code !== "CONCURRENT_UPDATE" && e.httpStatus !== 409) return error;
   if (e.code !== "CONCURRENT_UPDATE") return error;
   return new ConcurrentUpdateError({
     currentVersion: typeof details.currentVersion === "string" ? details.currentVersion : null,
     currentRecord: details.currentRecord ?? null,
-    message: typeof e.message === "string" ? e.message : void 0
+    message: typeof e.message === "string" ? e.message : void 0,
+    userMessage
   });
 }
 function formatHttpFailureMessage(message, meta) {
@@ -1563,6 +2457,80 @@ function createQuietHttpLogger() {
   };
   return logger;
 }
+var RECOGNIZED_DROP_REASONS = new Set(
+  DroppedFieldsEventSchema.shape.reason.options
+);
+var UNRECOGNIZED_DROP_REASON = "objectui:unrecognized-drop-reason";
+function isRecognizedDropReason(reason) {
+  return RECOGNIZED_DROP_REASONS.has(reason);
+}
+function isWireDroppedFieldsEntry(e) {
+  return !!e && typeof e === "object" && Array.isArray(e.fields) && e.fields.some((f) => typeof f === "string");
+}
+function asDroppedFieldsNotice(entry, fallbackObject) {
+  const fields = entry.fields.filter((f) => typeof f === "string");
+  const object = typeof entry.object === "string" ? entry.object : fallbackObject;
+  if (isRecognizedDropReason(entry.reason)) {
+    return { ...entry, object, fields, reason: entry.reason };
+  }
+  return {
+    ...entry,
+    object,
+    fields,
+    reason: UNRECOGNIZED_DROP_REASON,
+    unrecognizedReason: entry.reason
+  };
+}
+var UNATTRIBUTED_STRIP_OBJECT = "";
+var META_ROUTE_ABSENT_CODES = ["ROUTE_NOT_FOUND", "NOT_IMPLEMENTED"];
+var IMPORT_MAPPINGS_UNKNOWN_KIND_CODE = "INVALID_REQUEST";
+var IMPORT_MAPPINGS_UNKNOWN_KIND_STATUS = 400;
+var META_ABSENT_STATUSES = [404, 501];
+var META_REFUSAL_CODES = ["UNAUTHENTICATED", "PERMISSION_DENIED"];
+var META_REFUSAL_STATUSES = [401, 403, 405];
+function classifyImportMappingsFailure(error) {
+  const err = error ?? {};
+  const code = typeof err.code === "string" && err.code.length > 0 ? err.code : void 0;
+  const message = typeof err.message === "string" ? err.message : void 0;
+  const status = typeof err.httpStatus === "number" ? err.httpStatus : typeof err.status === "number" ? err.status : typeof err.statusCode === "number" ? err.statusCode : void 0;
+  const found = { code, status, message };
+  if (errorCodeIsAnyOf({ code }, META_ROUTE_ABSENT_CODES)) {
+    return { kind: "not-served", ...found };
+  }
+  if (errorCodeIs({ code }, IMPORT_MAPPINGS_UNKNOWN_KIND_CODE) && status === IMPORT_MAPPINGS_UNKNOWN_KIND_STATUS) {
+    return { kind: "not-served", ...found };
+  }
+  if (errorCodeIsAnyOf({ code }, META_REFUSAL_CODES)) {
+    return { kind: "refused", ...found };
+  }
+  if (status !== void 0 && META_REFUSAL_STATUSES.includes(status)) {
+    return { kind: "refused", ...found };
+  }
+  if (code === void 0 && status !== void 0 && META_ABSENT_STATUSES.includes(status)) {
+    return { kind: "not-served", ...found };
+  }
+  return { kind: "unreadable", ...found };
+}
+function classifyViewsFailure(error) {
+  const err = error ?? {};
+  const code = typeof err.code === "string" && err.code.length > 0 ? err.code : void 0;
+  const message = typeof err.message === "string" ? err.message : void 0;
+  const status = typeof err.httpStatus === "number" ? err.httpStatus : typeof err.status === "number" ? err.status : typeof err.statusCode === "number" ? err.statusCode : void 0;
+  const found = { code, status, message };
+  if (errorCodeIsAnyOf({ code }, META_ROUTE_ABSENT_CODES)) {
+    return { kind: "not-served", ...found };
+  }
+  if (errorCodeIsAnyOf({ code }, META_REFUSAL_CODES)) {
+    return { kind: "refused", ...found };
+  }
+  if (status !== void 0 && META_REFUSAL_STATUSES.includes(status)) {
+    return { kind: "refused", ...found };
+  }
+  if (code === void 0 && status !== void 0 && META_ABSENT_STATUSES.includes(status)) {
+    return { kind: "not-served", ...found };
+  }
+  return { kind: "unreadable", ...found };
+}
 function stableStringify(value) {
   if (value === null || typeof value !== "object") return JSON.stringify(value);
   if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
@@ -1595,20 +2563,14 @@ function withoutNoOpDrops(droppedFields, sent, stored) {
   }
   return out;
 }
+var VIEW_ITEM_ROUND_TRIP_KEYS = Object.keys(VIEW_CONSOLE_ROUND_TRIP_KEYS).filter((key) => VIEW_CONSOLE_ROUND_TRIP_KEYS[key].includes("viewItem"));
 function viewItemObjectName(item) {
   const spec = item?.list ?? item;
-  return spec?.data?.object ?? spec?.object ?? spec?.objectName;
+  return spec?.data?.object ?? spec?.object;
 }
 var VIEW_OVERLAY_MARKER = "_isOverride";
-function isLegacyOverlayRow(item, spec) {
-  if (spec && spec.config && typeof spec.config === "object") return false;
-  const viewKind = item?.viewKind ?? spec?.viewKind;
-  return viewKind === "list";
-}
 function isPersonalizationOverlayRow(item, spec) {
-  if (item?.[VIEW_OVERLAY_MARKER] === true) return true;
-  if (spec?.[VIEW_OVERLAY_MARKER] === true) return true;
-  return isLegacyOverlayRow(item, spec);
+  return item?.[VIEW_OVERLAY_MARKER] === true || spec?.[VIEW_OVERLAY_MARKER] === true;
 }
 var VIEW_OVERLAY_OWNED_KEYS = Object.freeze([
   "rowHeight",
@@ -1640,8 +2602,9 @@ function narrowPersonalizationOverlay(row) {
 function unwrapViewDraft(resp) {
   if (!resp || typeof resp !== "object") return null;
   const env = resp;
-  const body = "item" in env ? env.item : env;
-  if (!body || typeof body !== "object") return null;
+  const raw = "item" in env ? env.item : env;
+  if (!raw || typeof raw !== "object") return null;
+  const body = stripReadDecorations2(raw);
   const spec = body.list ?? body;
   if (!spec || typeof spec !== "object") return null;
   return Object.keys(spec).length > 0 ? spec : null;
@@ -1697,10 +2660,10 @@ var ObjectStackAdapter = class {
     // one adapter that has to cope with a backend lacking server atomicity (#2679).
     __publicField(this, "batchUnsupported", false);
     // The server's declared cross-object atomic-batch capability, read from
-    // discovery at connect() (framework #3298 / objectui #2693). `true` → the
+    // discovery at connect() (objectstack-ai/objectstack#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)
+    // error). `false` or `undefined` (capability absent → backend predates objectstack-ai/objectstack#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).
@@ -1711,7 +2674,7 @@ var ObjectStackAdapter = class {
     // inline-edit "Save All" writes without a manual reload.
     __publicField(this, "mutationListeners", /* @__PURE__ */ new Set());
     // Subscribers registered via onWriteWarning(). Emitted after a create/update
-    // whose response carried `droppedFields` (framework #3431/#3455) so the app
+    // whose response carried `droppedFields` (objectstack-ai/objectstack#3431 / objectstack-ai/objectstack#3455) so the app
     // shell can surface a toast instead of the strip passing silently.
     __publicField(this, "writeWarningListeners", /* @__PURE__ */ new Set());
     // Subscribers registered via onSaveAdvisory(). Emitted after a metadata save
@@ -1720,6 +2683,18 @@ var ObjectStackAdapter = class {
     // above in every respect except which door produced the event: that one is
     // record CRUD, this one is the metadata save door.
     __publicField(this, "saveAdvisoryListeners", /* @__PURE__ */ new Set());
+    // Subscribers registered via onMetadataReadWarning(). Emitted when a metadata
+    // READ failed in a way that is NOT the supported "this deployment does not
+    // serve that kind" shape, and was degraded to an empty result anyway
+    // (objectui#7741). Third sibling of the two sets above: same seam shape, and
+    // the opposite direction — those two describe a write that succeeded, this
+    // one a read that did not happen.
+    __publicField(this, "metadataReadWarningListeners", /* @__PURE__ */ new Set());
+    // [ADR-0066] The session's REPORTED system capabilities, pushed in by the
+    // host (see `setSystemCapabilities`). `undefined` means NO answer was ever
+    // reported — which is NOT the same as a reported-empty grant, and the two
+    // are treated differently by `maySetViewConfig` below.
+    __publicField(this, "systemCapabilities");
     this.client = new ObjectStackClient({ ...config, logger: createQuietHttpLogger() });
     this.installSaveAdvisoryInterceptor();
     this.metadataCache = new MetadataCache(config.cache);
@@ -1728,6 +2703,7 @@ var ObjectStackAdapter = class {
     this.reconnectDelay = config.reconnectDelay ?? 1e3;
     this.baseUrl = config.baseUrl;
     this.token = config.token;
+    this.systemCapabilities = config.systemCapabilities;
     this.fetchImpl = config.fetch || globalThis.fetch.bind(globalThis);
   }
   /**
@@ -1901,7 +2877,7 @@ var ObjectStackAdapter = class {
    * — 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).
+   * this path (objectstack-ai/objectstack#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
@@ -1934,10 +2910,10 @@ var ObjectStackAdapter = class {
     if (!res.ok) {
       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
-      );
+      const envelope = readErrorEnvelope(errorBody);
+      const err = new Error(envelope.message ?? res.statusText);
       err.status = res.status;
+      err.code = envelope.code;
       throw err;
     }
     const body = await res.json();
@@ -2040,24 +3016,28 @@ var ObjectStackAdapter = class {
     }
   }
   /**
-   * Read `droppedFields` off a create/update response (framework #3431/#3455)
+   * Read `droppedFields` off a create/update response (objectstack-ai/objectstack#3431 / objectstack-ai/objectstack#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.
+   *
+   * SHAPE decides whether an entry is an event at all (it must name at least one
+   * field); `object`, `fields` and `reason` are then PARSED — an unrecognized
+   * reason routed to the skew arm, a non-string field element refused, a missing
+   * `object` healed from `resource` — never asserted into the union, and the
+   * entry itself never dropped for them (objectui#4934, `f75810e7c`).
    */
   notifyDroppedFields(operation, resource, result, id, sent) {
     const dropped = result?.droppedFields;
     if (!Array.isArray(dropped) || dropped.length === 0) return;
-    const valid = dropped.filter(
-      (e) => !!e && typeof e === "object" && Array.isArray(e.fields) && e.fields.length > 0
-    );
+    const valid = dropped.filter(isWireDroppedFieldsEntry).map((e) => asDroppedFieldsNotice(e, resource));
     const stored = result?.record;
     const droppedFields = withoutNoOpDrops(valid, sent, stored);
     if (droppedFields.length === 0) return;
     this.emitWriteWarning({ operation, resource, ...id !== void 0 ? { id } : {}, droppedFields });
   }
   /**
-   * Same, for the cross-object transactional batch (framework #3794). Its
+   * Same, for the cross-object transactional batch (objectstack-ai/objectstack#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.
@@ -2073,13 +3053,13 @@ var ObjectStackAdapter = class {
     if (!Array.isArray(dropped) || dropped.length === 0) return;
     const results = payload?.results;
     for (const entry of dropped) {
-      if (!entry || typeof entry !== "object") continue;
+      if (!isWireDroppedFieldsEntry(entry)) 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 object = typeof e.object === "string" ? e.object : typeof op?.object === "string" ? op.object : UNATTRIBUTED_STRIP_OBJECT;
       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 }],
+        [asDroppedFieldsNotice({ fields: e.fields, reason: e.reason }, object)],
         op?.data,
         stored
       );
@@ -2087,7 +3067,7 @@ var ObjectStackAdapter = class {
       const operation = (op?.action ?? "create") === "create" ? "create" : "update";
       this.emitWriteWarning({
         operation,
-        resource: e.object ?? op?.object ?? "",
+        resource: object,
         ...op?.id !== void 0 && op?.id !== null ? { id: op.id } : {},
         droppedFields: [live]
       });
@@ -2095,7 +3075,7 @@ var ObjectStackAdapter = class {
   }
   /**
    * Subscribe to write-warning events (a create/update dropped caller-supplied
-   * fields — #3431/#3455). Returns an unsubscribe function. The app shell uses
+   * fields — objectstack-ai/objectstack#3431 / objectstack-ai/objectstack#3455). Returns an unsubscribe function. The app shell uses
    * this to toast the user; the write itself already succeeded.
    */
   onWriteWarning(callback) {
@@ -2109,7 +3089,7 @@ var ObjectStackAdapter = class {
    * advisory findings on a save that SUCCEEDED (#4237; backend
    * objectstack#7435). Returns an unsubscribe function.
    *
-   * Deliberately the same seam as {@link onWriteWarning} (#3431/#3455), which
+   * Deliberately the same seam as {@link onWriteWarning} (objectstack-ai/objectstack#3431 / objectstack-ai/objectstack#3455), which
    * is what {@link MetadataSaveAdvisoryEvent}'s own declaration already said it
    * was modelled on. It is a SIBLING of that channel rather than a second
    * payload pushed down it: `WriteWarningEvent` is a closed shape whose
@@ -2146,6 +3126,45 @@ var ObjectStackAdapter = class {
       }
     }
   }
+  /**
+   * Subscribe to metadata read-warning events — a metadata READ that could not
+   * be answered and was degraded to an empty result anyway (objectui#7741).
+   * Returns an unsubscribe function. The app shell uses this to toast the user;
+   * the caller has already been handed the empty result.
+   *
+   * Deliberately the same seam as {@link onWriteWarning} and
+   * {@link onSaveAdvisory}, and a SIBLING of them rather than a payload pushed
+   * down either: both of those announce a write that SUCCEEDED, and an event
+   * saying "this read did not happen" carried on one of them would make it lie
+   * about what occurred. What is reused is the seam's SHAPE — one long-lived
+   * instance with a `subscribe -> unsubscribe` registration that
+   * `AdapterProvider` wires once — not its event type.
+   *
+   * ⛔ Nothing here changes what a caller RECEIVES. `listImportMappings` still
+   * answers `[]` on every failure, including the loud ones; this channel is
+   * added ALONGSIDE that return, which is why it is not a change to a surface
+   * published since `@object-ui/data-objectstack@17.1.0`.
+   */
+  onMetadataReadWarning(callback) {
+    this.metadataReadWarningListeners.add(callback);
+    return () => {
+      this.metadataReadWarningListeners.delete(callback);
+    };
+  }
+  /**
+   * Notify all metadata read-warning subscribers. Isolated exactly like
+   * {@link emitWriteWarning}: a throwing listener must neither break the caller
+   * nor starve the others.
+   */
+  emitMetadataReadWarning(event) {
+    for (const listener of this.metadataReadWarningListeners) {
+      try {
+        listener(event);
+      } catch (err) {
+        console.warn("ObjectStackAdapter: metadata read-warning listener error", err);
+      }
+    }
+  }
   /**
    * Install the ONE emitter for the metadata save door (#4237).
    *
@@ -2203,6 +3222,12 @@ var ObjectStackAdapter = class {
           this.emitSaveAdvisory({
             type,
             name,
+            // #5026 — this interceptor wraps `meta.saveItem`, the SAVE door
+            // (`PUT /meta/:type/:name`) and only that one. The SDK's publish
+            // door (`meta.publishItem`) has no caller in this repo, so wiring
+            // it here would be a surface with no consumer; `MetadataClient` is
+            // where the publish door is actually taken.
+            door: "save",
             mode: result?.state === "draft" ? "draft" : "publish",
             advisories
           });
@@ -2250,7 +3275,7 @@ var ObjectStackAdapter = class {
         data,
         opts?.ifMatch ? { ifMatch: opts.ifMatch } : void 0
       );
-      this.emitMutation({ type: "update", resource, id, record: { ...result.record } });
+      this.emitMutation({ type: "update", resource, id: String(id), record: { ...result.record } });
       this.notifyDroppedFields("update", resource, result, id, data);
       return result.record;
     } catch (err) {
@@ -2273,7 +3298,7 @@ var ObjectStackAdapter = class {
         opts?.ifMatch ? { ifMatch: opts.ifMatch } : void 0
       );
       if (result.success) {
-        this.emitMutation({ type: "delete", resource, id });
+        this.emitMutation({ type: "delete", resource, id: String(id) });
       }
       return result.success;
     } catch (err) {
@@ -2374,25 +3399,25 @@ var ObjectStackAdapter = class {
    * @returns Promise resolving to array of results
    */
   /**
-   * Cross-object transactional batch (ObjectStack #1604 / ADR-0034 item 4).
+   * Cross-object transactional batch (objectstack-ai/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
+   * `data.batchTransaction` (objectstack-ai/objectstack#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 /
+   * Fallback decision — declarative capability negotiation (objectstack-ai/objectstack#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
+   *   - Declared `false`, or ABSENT (backend predates objectstack-ai/objectstack#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
@@ -2816,9 +3841,10 @@ var ObjectStackAdapter = class {
     const res = await this.fetchImpl(url, { method: "GET", headers });
     if (!res.ok) {
       const errorBody = await res.json().catch(() => ({ message: res.statusText }));
-      const err = new Error(errorBody?.error?.message || errorBody?.message || res.statusText);
+      const envelope = readErrorEnvelope(errorBody);
+      const err = new Error(envelope.message ?? res.statusText);
       err.status = res.status;
-      err.code = errorBody?.code ?? errorBody?.error?.code;
+      err.code = envelope.code;
       err.httpStatus = res.status;
       throw err;
     }
@@ -2868,16 +3894,51 @@ var ObjectStackAdapter = class {
         queryParams.set("searchFields", request.searchFields.join(","));
       }
     }
+    return this.fetchExportBlob(resource, queryParams);
+  }
+  /**
+   * Download the server's import template:
+   * `GET /api/v1/data/:object/export?template=true` (objectui#9600).
+   *
+   * Same route as {@link exportDownload}, with the server's template switch. It
+   * sends only `template=true`: the server refuses the export's row parameters
+   * on a template request, and its answer is always an xlsx workbook.
+   *
+   * The server writes the template's labels in the request's locale, and the
+   * import accepts a translated label only in its own request's locale. The
+   * import request goes through `@objectstack/client`, which stamps
+   * `Accept-Language` with the client's locale when one is set (and the host's
+   * `fetch` stamps its own otherwise). This request bypasses the client, so it
+   * stamps the client's locale the same way. Both requests then carry the same
+   * locale.
+   */
+  async downloadImportTemplate(resource) {
+    const locale = this.client.getLocale();
+    return this.fetchExportBlob(
+      resource,
+      new URLSearchParams({ template: "true" }),
+      locale ? { "Accept-Language": locale } : void 0
+    );
+  }
+  /**
+   * GET `/api/v1/data/:object/export` with the given query and answer the body
+   * as a Blob. A failure throws an `Error` that carries the server's `status`
+   * and its ADR-0112 `code`. The one request path {@link exportDownload} and
+   * {@link downloadImportTemplate} share.
+   */
+  async fetchExportBlob(resource, queryParams, extraHeaders) {
     const baseUrl = this.baseUrl.replace(/\/$/, "");
     const hasApiVersionSuffix = /\/api\/v\d+$/i.test(baseUrl);
     const dataPath = hasApiVersionSuffix ? "/data" : "/api/v1/data";
     const url = `${baseUrl}${dataPath}/${encodeURIComponent(resource)}/export?${queryParams.toString()}`;
-    const headers = { ...this.getAuthHeaders() };
+    const headers = { ...this.getAuthHeaders(), ...extraHeaders };
     const res = await this.fetchImpl(url, { method: "GET", headers, credentials: "include" });
     if (!res.ok) {
       const errorBody = await res.json().catch(() => ({ message: res.statusText }));
-      const err = new Error(errorBody?.error?.message || errorBody?.message || res.statusText);
+      const envelope = readErrorEnvelope(errorBody);
+      const err = new Error(envelope.message ?? res.statusText);
       err.status = res.status;
+      err.code = envelope.code;
       throw err;
     }
     return await res.blob();
@@ -2898,7 +3959,8 @@ var ObjectStackAdapter = class {
         if (Array.isArray(params.$filter)) {
           options.filters = translateFilterArray(params.$filter);
         } else {
-          options.filters = convertFiltersToAST(params.$filter);
+          const lowered = convertFiltersToAST(params.$filter);
+          if (lowered !== void 0) options.filters = lowered;
         }
       }
     }
@@ -3018,13 +4080,16 @@ var ObjectStackAdapter = class {
     });
     if (!res.ok) {
       const errBody = await res.json().catch(() => ({ message: res.statusText }));
-      const err = new Error(errBody?.error?.message || errBody?.message || res.statusText);
+      const envelope = readErrorEnvelope(errBody);
+      const err = new Error(envelope.message ?? res.statusText);
       err.status = res.status;
+      err.code = envelope.code;
       throw err;
     }
     const body = await res.json();
     const data = body && typeof body === "object" && "success" in body && "data" in body ? body.data : body;
-    return data && typeof data === "object" && "item" in data ? data.item : data;
+    const item = data && typeof data === "object" && "item" in data ? data.item : data;
+    return attachObjectSortability(item, data && typeof data === "object" ? data.sortability : void 0);
   }
   /**
    * List every registered object (code- and DB-defined) from the metadata
@@ -3251,7 +4316,42 @@ var ObjectStackAdapter = class {
    *   (vs. a system view being personalized for the first time). Omit /
    *   `false` for the default overlay-marking behavior.
    */
+  /**
+   * [ADR-0066] Tell this adapter which system capabilities the session holds.
+   *
+   * Pass `undefined` for "no answer was reported" (a backend predating
+   * ADR-0066, or no permission provider mounted). Pass `[]` for a real,
+   * reported, empty grant — {@link maySetViewConfig} treats those two
+   * differently and callers must not collapse them, which is the same
+   * distinction `MePermissionsProvider` preserves natively (objectui#4656).
+   */
+  setSystemCapabilities(capabilities) {
+    this.systemCapabilities = capabilities ? [...capabilities] : void 0;
+  }
+  /**
+   * May this session write ORG-WIDE view configuration?
+   *
+   * **Unknown fails OPEN**, deliberately, and this is the one judgement in the
+   * gate worth reading twice. It is the doctrine `PermissionContextValue`
+   * .`hasCapabilities` states for every ADR-0066 gate in this repo
+   * (objectui#4656, framework#3923): the server enforces `manage_metadata` on
+   * the metadata door regardless of what the client believes, so a client-side
+   * denial on MISSING DATA cannot protect anything the server was not already
+   * protecting — it can only break a permitted user. Failing closed here would
+   * have refused the write on every deployment predating ADR-0066 and every
+   * host with no permission provider, which is "break the write for everyone"
+   * wearing the costume of a security fix.
+   *
+   * A REPORTED empty array gates strictly: "holds nothing" is a real answer.
+   */
+  maySetViewConfig() {
+    if (this.systemCapabilities === void 0) return true;
+    return this.systemCapabilities.includes(VIEW_CONFIG_CAPABILITY);
+  }
   async updateViewConfig(objectName, viewId, config, opts) {
+    if (!this.maySetViewConfig()) {
+      throw new ViewConfigPermissionDeniedError(objectName, viewId);
+    }
     await this.connect();
     const merged = {
       ...config || {},
@@ -3279,6 +4379,42 @@ var ObjectStackAdapter = class {
    * the metadata index is name-only, not field-typed, so the route has no
    * `?object=` to push the filter down into. {@link listViewOverrides}
    * reads the same rows through the same accessor.
+   *
+   * ## Every failure still degrades to an empty list — and now says which kind
+   * ## of failure it was (objectui#8151)
+   *
+   * The degrade is unchanged and deliberate, exactly as it is one method over
+   * in {@link listImportMappings}: a host with no metadata door keeps answering
+   * `[]` rather than breaking the page. What changed is that the OTHER failures
+   * no longer render as that one.
+   *
+   * This method's empty list is read as *this object has no saved views*, and
+   * that reading reaches the user in two places measured on this tree: the list
+   * view switcher simply shows fewer tabs, and `@object-ui/core`'s
+   * `elementDataSourceViewNotFoundMessage` states it outright. So a session
+   * whose token lapsed mid-read was shown an object that appears to have no
+   * saved views AT ALL — including ones the user created — with a
+   * `console.warn` as the only discriminator, in a console nothing in the UI
+   * points at. That is the silence objectui#7741 removed from the sibling after
+   * it produced a confident wrong diagnosis in objectstack#14026.
+   *
+   * The `catch` now asks {@link classifyViewsFailure} what the failure WAS,
+   * reading the error's own ADR-0112 `code` and status — never "is the result
+   * empty", which is what both conditions produce and so can never tell them
+   * apart — and anything that is not the doorless shape is announced on
+   * {@link onMetadataReadWarning}.
+   *
+   * ⛔ That classifier is a SEPARATE reading, not a second caller of the
+   * sibling's: `view`'s quiet set is strictly smaller, because the arm
+   * `listImportMappings` is built around (*an older server without this kind*)
+   * has no members here. See {@link classifyViewsFailure} for the measurement.
+   *
+   * ⛔ The RETURN is untouched. This method has answered `Promise<any[]>`, never
+   * throwing, since `@object-ui/data-objectstack@17.1.0`; a consumer that reads
+   * nothing new sees exactly what it saw before, including on the loud arms.
+   * Applying framework objectstack#13906 decision 1 option A — *a thing that could not be
+   * READ is not a thing that is ABSENT* — is done by ADDING a channel, not by
+   * moving that contract.
    */
   async listViews(objectName, options) {
     await this.connect();
@@ -3304,18 +4440,35 @@ var ObjectStackAdapter = class {
         const spec = v.list ?? v;
         const isDraft = v._draft === true || spec?._draft === true;
         if (spec && spec.config && typeof spec.config === "object") {
-          return {
+          const row = {
             ...spec.config,
             name: spec.name ?? spec.config.name,
-            label: spec.label ?? spec.config.label,
-            isDefault: !!spec.isDefault,
-            ...isDraft ? { _draft: true } : {}
+            label: spec.label ?? spec.config.label
           };
+          if (spec.object !== void 0) row.object = spec.object;
+          for (const key of VIEW_ITEM_ROUND_TRIP_KEYS) {
+            if (spec[key] !== void 0) row[key] = spec[key];
+          }
+          row.isDefault = !!spec.isDefault;
+          if (isDraft) row._draft = true;
+          return row;
         }
         return isDraft ? { ...spec, _draft: true } : spec;
       });
     } catch (err) {
       console.warn("[OBJECTSTACKDataSource] listViews failed:", err);
+      const failure = classifyViewsFailure(err);
+      if (failure.kind !== "not-served") {
+        this.emitMetadataReadWarning({
+          operation: "listViews",
+          kind: "view",
+          objectName,
+          reason: failure.kind,
+          ...failure.code !== void 0 ? { code: failure.code } : {},
+          ...failure.status !== void 0 ? { status: failure.status } : {},
+          ...failure.message !== void 0 ? { message: failure.message } : {}
+        });
+      }
       return [];
     }
   }
@@ -3334,11 +4487,36 @@ var ObjectStackAdapter = class {
   }
   /**
    * List registered import `mapping` artifacts targeting a given object
-   * (framework #2611). Reads the `mapping` metadata kind via the overlay API
+   * (objectstack-ai/objectstack#2611). Reads the `mapping` metadata kind via the overlay API
    * and filters by `targetObject` client-side (the metadata index is
-   * name-only). Feeds the import wizard's "saved mapping" selector; a failure
-   * (older server without the `mapping` kind) degrades to an empty list, so
-   * the selector simply doesn't appear.
+   * name-only). Feeds the import wizard's "saved mapping" selector.
+   *
+   * ## Every failure still degrades to an empty list — and now says which kind
+   * ## of failure it was (objectui#7741)
+   *
+   * The degrade is unchanged and deliberate: an older server without the
+   * `mapping` kind must not break the wizard, so it keeps answering `[]` and
+   * the selector simply doesn't appear. That is a real, supported deployment
+   * shape and it stays quiet.
+   *
+   * What changed is that the OTHER failures no longer render as that one. A
+   * refused door and a broken one used to be indistinguishable, in the UI, from
+   * "no mapping is registered" — both were an empty list behind a
+   * `console.warn` nothing pointed at — and that silence produced a confident
+   * wrong diagnosis in a careful reporter (objectstack#14026 was filed, routed
+   * and worked by two seats against a wizard that had been correct since
+   * 17.1.0). So the `catch` now asks {@link classifyImportMappingsFailure} what
+   * the failure WAS, reading the error's own ADR-0112 `code` and status —
+   * never "is the result empty", which is what both conditions produce and so
+   * can never tell them apart — and anything that is not the supported
+   * kind-absent shape is announced on {@link onMetadataReadWarning}.
+   *
+   * ⛔ The RETURN is untouched. This method has answered `Promise<any[]>`, never
+   * throwing, since `@object-ui/data-objectstack@17.1.0`; a consumer that reads
+   * nothing new sees exactly what it saw before, including on the loud arms.
+   * Applying framework objectstack#13906 decision 1 option A — *a thing that could not be
+   * READ is not a thing that is ABSENT* — is done by ADDING a channel, not by
+   * moving that contract.
    */
   async listImportMappings(objectName) {
     await this.connect();
@@ -3348,6 +4526,18 @@ var ObjectStackAdapter = class {
       return items.filter((m) => m && m.targetObject === objectName);
     } catch (err) {
       console.warn("[OBJECTSTACKDataSource] listImportMappings failed:", err);
+      const failure = classifyImportMappingsFailure(err);
+      if (failure.kind !== "not-served") {
+        this.emitMetadataReadWarning({
+          operation: "listImportMappings",
+          kind: "mapping",
+          objectName,
+          reason: failure.kind,
+          ...failure.code !== void 0 ? { code: failure.code } : {},
+          ...failure.status !== void 0 ? { status: failure.status } : {},
+          ...failure.message !== void 0 ? { message: failure.message } : {}
+        });
+      }
       return [];
     }
   }
@@ -3602,11 +4792,17 @@ var ObjectStackAdapter = class {
    *
    * The maintainer ruling (2026-08-12) put the answer on the BY-NAME route
    * rather than in the list, so the enumeration surface is not widened past what
-   * a by-name probe already implies (objectstack#8013 / PR #8135): an app that
+   * a by-name probe already implies (objectstack#8013 / PR objectstack-ai/objectstack#8135): an app that
    * exists and whose `requiredPermissions` the session lacks answers `403` with
    * `PERMISSION_DENIED` in the declared envelope, and absence — a nonexistent
-   * name, an unpublished app, an app gated by an absent optional service —
-   * keeps answering `404 RESOURCE_NOT_FOUND`.
+   * name, an unpublished app, an app gated by an absent optional service — is
+   * one undifferentiated answer.
+   *
+   * ⚠️ That absence is NOT uniformly a `404`, which this docstring asserted
+   * until objectui#9262 measured it: the 404 covers an app that EXISTS and is
+   * withheld for a non-permission reason, while a name that resolves to nothing
+   * answers `200` with an envelope carrying no `item`. Both are absence and both
+   * read as `not_found`; see {@link metaEnvelopeCarriesItem} for the measurement.
    *
    * ## Why this is a separate method and not a flavour of {@link getApp}
    *
@@ -3617,19 +4813,41 @@ var ObjectStackAdapter = class {
    *    be cached beside a document about the APP — one grant, and a cached
    *    denial outlives the session it described.
    *
-   * Nothing here throws: a probe that cannot reach an answer returns `unknown`
-   * and the caller keeps whatever it was already showing. Only the measured
-   * `code` produces `denied` — never a status, never a message (objectui#4408).
+   * Nothing here throws: every outcome is a verdict the caller renders a screen
+   * from, never a catch block. Only the measured `code` produces `denied` —
+   * never a status, never a message (objectui#4408).
+   *
+   * ## objectui#9262 — what this method stopped folding away
+   *
+   * It used to answer `granted` whenever the call did not throw, and `unknown`
+   * for everything that did. Both halves were wrong in the same direction, and
+   * the first was measured on a real server before this change landed:
+   *
+   *  - **an app that does not exist answers `200` with the envelope minus its
+   *    `item`**, so "did not throw" reported `granted` for a name with nothing
+   *    behind it — the shape issue objectui#9262 listed as cause 8 and expected
+   *    to be structural. It is the ordinary case: every typo, every never-created
+   *    app and every unpublished draft took it. See
+   *    {@link metaEnvelopeCarriesItem} for the measurement and the server-side
+   *    mechanism.
+   *  - a 404 absence and an unreachable server were one `unknown`, though the
+   *    transport had already told them apart.
+   *
+   * The verdicts now say only what was obtained: a served document, a refusal
+   * naming permission, an answer that there is no such app here, or no answer
+   * at all. `unknown` is left for the one case where nothing was asked.
    *
    * @param appName - the app name as it appears in the URL segment
    */
   async probeAppAccess(appName) {
     if (!appName) return "unknown";
     try {
-      await this.client.meta.getItem("app", appName);
-      return "granted";
+      const envelope = await this.client.meta.getItem("app", appName);
+      return metaEnvelopeCarriesItem(envelope) ? "granted" : "not_found";
     } catch (err) {
-      return isAppPermissionDeniedError(err) ? "denied" : "unknown";
+      if (isAppPermissionDeniedError(err)) return "denied";
+      if (isMetaItemAbsentError(err)) return "not_found";
+      return "unreachable";
     }
   }
   /**
@@ -3679,7 +4897,8 @@ var ObjectStackAdapter = class {
    * Uses `this.client.analytics.query()` from @objectstack/client to leverage
    * the SDK's built-in auth, headers, and fetch configuration.
    * Falls back to client-side aggregation via find() if the analytics endpoint
-   * is not available.
+   * is not available. Throws {@link AnalyticsResultShapeError} when it answers
+   * with anything but an `AnalyticsResult` carrying `rows`.
    */
   async aggregate(resource, params) {
     await this.connect();
@@ -3688,7 +4907,11 @@ var ObjectStackAdapter = class {
       const queryAst = {};
       if (Array.isArray(params.groupBy)) queryAst.groupBy = params.groupBy;
       if (Array.isArray(params.aggregations)) queryAst.aggregations = params.aggregations;
-      if (params.where !== void 0) queryAst.where = params.where;
+      if (params.where !== void 0) {
+        assertSpecShapeWhereIsFilterAst(params.where, resource);
+        queryAst.where = params.where;
+      }
+      assertNoAnalyticsKeysOnSpecShape(params, resource);
       if (typeof params.limit === "number") queryAst.limit = params.limit;
       const result = await this.client.data.query(resource, queryAst);
       if (Array.isArray(result)) return result;
@@ -3696,6 +4919,7 @@ var ObjectStackAdapter = class {
       if (Array.isArray(result?.data)) return result.data;
       return [];
     }
+    const analyticsWhere = params.filter ? lowerAnalyticsFilterForWire(params.filter, resource) : void 0;
     try {
       const measureName = params.function === "count" ? "count" : `${params.field}_${params.function}`;
       const valueKey = this.aggregateValueKey(params);
@@ -3705,11 +4929,12 @@ var ObjectStackAdapter = class {
         // When groupBy is '_all' no dimensions are needed (single-bucket).
         dimensions: params.groupBy && params.groupBy !== "_all" ? [params.groupBy] : []
       };
-      if (params.filter) {
-        payload.where = params.filter;
+      if (analyticsWhere !== void 0) payload.where = analyticsWhere;
+      const contractResult = await this.client.analytics.query(payload);
+      if (!Array.isArray(contractResult?.rows)) {
+        throw new AnalyticsResultShapeError(resource, contractResult);
       }
-      const data = await this.client.analytics.query(payload);
-      const rawRows = Array.isArray(data) ? data : data?.rows && Array.isArray(data.rows) ? data.rows : data?.data && Array.isArray(data.data) ? data.data : data?.data?.rows && Array.isArray(data.data.rows) ? data.data.rows : data?.results && Array.isArray(data.results) ? data.results : [];
+      const rawRows = contractResult.rows;
       const measureMissing = rawRows.length > 0 && rawRows.every((row) => {
         if (row == null) return true;
         if (measureName in row && row[measureName] != null) return false;
@@ -3728,6 +4953,7 @@ var ObjectStackAdapter = class {
         return mapped;
       });
     } catch (e) {
+      if (e instanceof AnalyticsResultShapeError) throw e;
       const failure = classifyAnalyticsFailure(e);
       if (failure.kind === "rejected") {
         throw new AnalyticsQueryRejectedError(failure.message, failure.code);
@@ -3747,6 +4973,34 @@ var ObjectStackAdapter = class {
       return await this.aggregateViaFind(resource, params);
     }
   }
+  /**
+   * Answer a grouped list view's GROUP HEADER query (objectui#7189) — see
+   * `DataSource.queryGroupHeaders` in `@object-ui/types` for the contract.
+   *
+   * The compiled query rides the platform's EXISTING data door verbatim:
+   * `client.data.query()` posts it to `POST /data/:object/query`, whose
+   * `findData` routes a body carrying `groupBy` / `aggregations` to
+   * `engine.aggregate` and answers the header rows as `records` (the door the
+   * spec half of objectstack#14556 names, pinned platform-side by
+   * objectstack#15330). No new route, no new wire shape.
+   *
+   * ⛔ No fallback, deliberately — unlike {@link aggregate}. A header query that
+   * degraded to bucketing a fetched page would answer page slices under a name
+   * that promises the query's own numbers, which is the defect this member
+   * exists to end. A failure is thrown to the caller, and a body without a
+   * `records` array is refused rather than read as "no groups".
+   */
+  async queryGroupHeaders(resource, query) {
+    await this.connect();
+    const result = await this.client.data.query(resource, query);
+    const records = result?.records;
+    if (!Array.isArray(records)) {
+      throw new Error(
+        `queryGroupHeaders('${resource}'): POST /data/${resource}/query answered without a \`records\` array, so no group header can be read from it. The header query was sent verbatim; nothing was approximated from a page of rows.`
+      );
+    }
+    return records;
+  }
   /**
    * Client-side aggregation over a server-scoped `find()` — the fallback used
    * whenever the analytics endpoint cannot answer (capability absent, network
@@ -3842,6 +5096,13 @@ var ObjectStackAdapter = class {
       if (errorCodeIs({ code: serverCode }, "UNAUTHENTICATED")) {
         throw new AnalyticsUnauthenticatedError({ serverCode, serverMessage });
       }
+      if (errorCodeIs({ code: serverCode }, "PERMISSION_DENIED")) {
+        throw new AnalyticsForbiddenError({
+          serverCode,
+          serverMessage,
+          datasetName: requestedDatasetName
+        });
+      }
       if (serverCode === void 0) {
         if (ANALYTICS_ABSENT_STATUSES.includes(res.status)) {
           throw new AnalyticsNotInstalledError(surface, detail || void 0);
@@ -3982,9 +5243,10 @@ var ObjectStackAdapter = class {
       }
     });
     if (!response.ok) {
-      const error = await response.json().catch(() => ({ message: response.statusText }));
+      const errorBody = await response.json().catch(() => ({ message: response.statusText }));
+      const envelope = readErrorEnvelope(errorBody);
       throw new ObjectStackError(
-        error.message || `Upload failed with status ${response.status}`,
+        envelope.message ?? `Upload failed with status ${response.status}`,
         "UPLOAD_ERROR",
         response.status
       );
@@ -4024,9 +5286,10 @@ var ObjectStackAdapter = class {
       }
     });
     if (!response.ok) {
-      const error = await response.json().catch(() => ({ message: response.statusText }));
+      const errorBody = await response.json().catch(() => ({ message: response.statusText }));
+      const envelope = readErrorEnvelope(errorBody);
       throw new ObjectStackError(
-        error.message || `Upload failed with status ${response.status}`,
+        envelope.message ?? `Upload failed with status ${response.status}`,
         "UPLOAD_ERROR",
         response.status
       );
@@ -4108,28 +5371,46 @@ export {
   API_ACCESS_DENIED_CODES,
   APP_PERMISSION_DENIED_CODE,
   AnalyticsDatasetNotFoundError,
+  AnalyticsForbiddenError,
+  AnalyticsKeysOnSpecShapeError,
   AnalyticsNotInstalledError,
   AnalyticsQueryRejectedError,
+  AnalyticsResultShapeError,
   AnalyticsUnauthenticatedError,
   AuthenticationError,
   BulkOperationError,
+  CHOICE_TYPES_REQUIRING_OPTIONS,
   ConcurrentUpdateError,
   ConnectionError,
   DataApiValidationError,
   FILTER_OPERATOR_ALIASES,
+  META_ITEM_ABSENT_CODE,
   MalformedFilterError,
   MetadataClient,
   MetadataNotFoundError,
+  OBJECT_METADATA_TYPE,
   ObjectStackAdapter,
   ObjectStackError,
+  RELATIONSHIP_TYPES_REQUIRING_REFERENCE,
+  UNRECOGNIZED_DROP_REASON,
+  UnlowerableAnalyticsFilterError,
+  UnloweredAggregateWhereError,
+  VIEW_CONFIG_CAPABILITY,
   VIEW_OVERLAY_OWNED_KEYS,
+  ViewConfigPermissionDeniedError,
+  assertObjectMetadataWritable,
   classifyAnalyticsFailure,
+  classifyImportMappingsFailure,
+  classifyViewsFailure,
   clearSharedDiscoveryCache,
   createErrorFromResponse,
   createObjectStackAdapter,
   createObjectStackUserStateAdapter,
   createQuietHttpLogger,
+  extractDraftBody,
   formatHttpFailureMessage,
+  formatMetadataError,
+  formatMetadataIssue,
   getSharedDiscovery,
   is404Error,
   isAnalyticsNotInstalledError,
@@ -4138,7 +5419,9 @@ export {
   isConcurrentUpdateError,
   isErrorType,
   isMalformedFilterError,
+  isMetaItemAbsentError,
   isObjectStackError,
+  isViewConfigPermissionDeniedError,
   narrowPersonalizationOverlay,
   normaliseClientError,
   readSaveAdvisories,