@object-ui/data-objectstack 17.5.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");
@@ -246,7 +378,6 @@ var MetadataClient = class _MetadataClient {
       "Content-Type": "application/json"
     };
     if (options.ifMatch) headers["If-Match"] = options.ifMatch;
-    if (options.actor) headers["X-Actor"] = options.actor;
     const res = await this.fetchImpl(url, {
       method: "PUT",
       headers,
@@ -254,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;
   }
   /**
@@ -281,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`;
@@ -291,24 +469,122 @@ 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;
   }
   /**
-   * Get the 3-state layered view of a metadata item (Phase 3a). Returns
-   * `code` (the artifact / fallback default), `overlay` (the saved
-   * customisation, if any), and `effective` (what the runtime sees).
+   * 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
+   * artifact baseline), `overlay` (the tenant customisation row alone) and
+   * `effective` (the merged value the runtime sees).
+   *
+   * Reads **`GET /meta/:type/:name/layers`** — the path the framework declares
+   * for this projection, with a response schema of its own
+   * (`GetMetaItemLayeredResponseSchema`, objectstack#5882 ruling B). It used to
+   * be reached by hanging a `layers` flag on the ordinary item read, which made
+   * one route answer two unrelated representations while `packages/spec`
+   * declared only one of them. That spelling still answers this same body
+   * inside its deprecation window (the response carries RFC 9745
+   * `Deprecation: true` and an RFC 8288 `Link: rel="successor-version"` back to
+   * this path) and is scheduled for removal upstream, so nothing here may
+   * depend on it — the repo-wide ratchet is
+   * `scripts/__tests__/layered-read-declared-path-4016.test.ts`.
+   *
+   * The request is built here rather than delegated to `@objectstack/client`
+   * because the SDK expresses no layered read in EITHER spelling: the
+   * framework's REST route ledger records this route as `server-only`,
+   * "consumed by objectui over plain HTTP", and whether the SDK should express
+   * it is an open upstream product call.
+   *
+   * One behaviour delta rides along with the path, and it is the server's
+   * choice rather than ours: the retired flag FELL THROUGH to the plain item
+   * read on a backend whose protocol implementation had no layered support,
+   * answering the `{ type, name, item }` envelope. A dedicated path refuses to
+   * answer a different resource under this one's declared shape, so it returns
+   * 501 `NOT_IMPLEMENTED` instead — which surfaces here as a thrown error
+   * rather than a view with `code` and `overlay` silently blank.
    */
   async layered(type, name, options = {}) {
-    const pkg = options.packageId ? `&package=${encodeURIComponent(options.packageId)}` : "";
-    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}?layers=true${pkg}`;
+    const qs = options.packageId ? `?package=${encodeURIComponent(options.packageId)}` : "";
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/layers${qs}`;
     const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
     if (res.status === 404) {
       return { code: null, overlay: null, overlayScope: null, effective: null };
     }
     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,
@@ -317,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 } : {},
@@ -334,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 } : {}
     };
   }
   /**
@@ -391,7 +688,6 @@ var MetadataClient = class _MetadataClient {
     const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}${qs}`;
     const headers = { ...this.headers };
     if (options.ifMatch) headers["If-Match"] = options.ifMatch;
-    if (options.actor) headers["X-Actor"] = options.actor;
     const res = await this.fetchImpl(url, { method: "DELETE", headers });
     if (!res.ok) throw await parseError(res);
     return await res.json();
@@ -402,21 +698,29 @@ 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"
     };
-    if (options.actor) headers["X-Actor"] = options.actor;
     const res = await this.fetchImpl(url, {
       method: "POST",
       headers,
       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`).
@@ -432,7 +736,6 @@ var MetadataClient = class _MetadataClient {
       ...this.headers,
       "Content-Type": "application/json"
     };
-    if (options.actor) headers["X-Actor"] = options.actor;
     const res = await this.fetchImpl(url, {
       method: "POST",
       headers,
@@ -512,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": "=",
@@ -531,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") {
@@ -562,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 }
           );
         }
       }
@@ -576,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) {
@@ -583,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) {
@@ -651,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;
 }
 
@@ -1037,50 +1681,23 @@ function isErrorType(error, errorClass) {
   return error instanceof errorClass;
 }
 
-// src/contracts.ts
-function validatePluginContract(contract) {
-  const errors = [];
-  const warnings = [];
-  if (!contract.name || contract.name.trim().length === 0) {
-    errors.push({ field: "name", message: "Plugin name is required", code: "MISSING_NAME" });
-  }
-  if (!contract.version || !/^\d+\.\d+\.\d+/.test(contract.version)) {
-    errors.push({ field: "version", message: "Valid semver version is required", code: "INVALID_VERSION" });
-  }
-  if (!contract.exports || contract.exports.length === 0) {
-    errors.push({ field: "exports", message: "At least one export is required", code: "NO_EXPORTS" });
-  }
-  if (contract.exports) {
-    const validTypes = ["component", "hook", "utility", "provider"];
-    for (const exp of contract.exports) {
-      if (!exp.name) {
-        errors.push({ field: "exports.name", message: "Export name is required", code: "MISSING_EXPORT_NAME" });
-      }
-      if (!validTypes.includes(exp.type)) {
-        errors.push({ field: "exports.type", message: `Invalid export type: ${exp.type}`, code: "INVALID_EXPORT_TYPE" });
-      }
-    }
-  }
-  if (!contract.permissions || contract.permissions.length === 0) {
-    warnings.push("No permissions declared \u2014 plugin will have minimal access");
-  }
-  return { valid: errors.length === 0, errors, warnings };
+// 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 generateContractManifest(contract) {
-  return {
-    $schema: "https://objectui.org/schemas/plugin-contract-v1.json",
-    name: contract.name,
-    version: contract.version,
-    peerDependencies: contract.peerDependencies ?? {},
-    exports: contract.exports.map((exp) => ({
-      name: exp.name,
-      type: exp.type,
-      description: exp.description ?? ""
-    })),
-    permissions: contract.permissions ?? [],
-    api: contract.api ?? {},
-    generatedAt: (/* @__PURE__ */ new Date()).toISOString()
-  };
+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
@@ -1185,265 +1802,31 @@ function createObjectStackUserStateAdapter(options) {
   };
 }
 
-// src/integration.ts
-var IntegrationManager = class {
-  constructor() {
-    __publicField(this, "integrations", /* @__PURE__ */ new Map());
-  }
-  /**
-   * Register a new integration.
-   */
-  register(id, config) {
-    this.integrations.set(id, config);
-  }
-  /**
-   * Remove an integration.
-   */
-  unregister(id) {
-    this.integrations.delete(id);
-  }
-  /**
-   * Get all registered integrations.
-   */
-  getAll() {
-    return new Map(this.integrations);
-  }
-  /**
-   * Get integrations that match a specific event.
-   */
-  getForEvent(event) {
-    return Array.from(this.integrations.values()).filter(
-      (integration) => integration.enabled && integration.triggers?.some((t) => t.event === event)
-    );
-  }
-  /**
-   * Dispatch an event to all matching integrations.
-   * Returns results for each integration.
-   */
-  async dispatch(event, payload) {
-    const matching = this.getForEvent(event);
-    const results = [];
-    for (const [id, integration] of this.integrations) {
-      if (!matching.includes(integration)) continue;
-      try {
-        await this.send(integration, payload);
-        results.push({ id, success: true });
-      } catch (err) {
-        results.push({ id, success: false, error: err.message });
-      }
-    }
-    return results;
-  }
-  /**
-   * Send payload to a specific integration.
-   */
-  async send(integration, payload) {
-    switch (integration.provider) {
-      case "webhook": {
-        const cfg = integration.config;
-        const url = cfg.url;
-        try {
-          const parsed = new URL(url);
-          if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-            throw new Error(`Invalid URL protocol: ${parsed.protocol}`);
-          }
-        } catch (e) {
-          if (e instanceof TypeError) {
-            throw new Error(`Invalid webhook URL: ${url}`);
-          }
-          throw e;
-        }
-        await fetch(url, {
-          method: cfg.method,
-          headers: {
-            "Content-Type": "application/json",
-            ...cfg.headers
-          },
-          body: JSON.stringify(payload)
-        });
-        break;
-      }
-      case "slack": {
-        const cfg = integration.config;
-        const url = cfg.webhookUrl;
-        try {
-          const parsed = new URL(url);
-          if (parsed.protocol !== "https:") {
-            throw new Error(`Invalid Slack webhook URL protocol: ${parsed.protocol}`);
-          }
-        } catch (e) {
-          if (e instanceof TypeError) {
-            throw new Error(`Invalid Slack webhook URL: ${url}`);
-          }
-          throw e;
-        }
-        await fetch(url, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({
-            channel: cfg.channel,
-            username: cfg.username,
-            icon_emoji: cfg.iconEmoji,
-            text: JSON.stringify(payload)
-          })
-        });
-        break;
-      }
-      // Email and other providers would require server-side implementation
-      default:
-        break;
-    }
-  }
-};
-
-// src/security.ts
-var SecurityManager = class {
-  constructor(policy = {}) {
-    __publicField(this, "policy");
-    __publicField(this, "auditLog", []);
-    this.policy = policy;
-  }
-  /**
-   * Generate a CSP header string from the configuration.
-   */
-  generateCSPHeader() {
-    const csp = this.policy.csp;
-    if (!csp) return "";
-    const directives = [];
-    if (csp.scriptSrc?.length) directives.push(`script-src ${csp.scriptSrc.join(" ")}`);
-    if (csp.styleSrc?.length) directives.push(`style-src ${csp.styleSrc.join(" ")}`);
-    if (csp.imgSrc?.length) directives.push(`img-src ${csp.imgSrc.join(" ")}`);
-    if (csp.connectSrc?.length) directives.push(`connect-src ${csp.connectSrc.join(" ")}`);
-    if (csp.fontSrc?.length) directives.push(`font-src ${csp.fontSrc.join(" ")}`);
-    if (csp.frameSrc?.length) directives.push(`frame-src ${csp.frameSrc.join(" ")}`);
-    if (csp.reportUri) directives.push(`report-uri ${csp.reportUri}`);
-    return directives.join("; ");
-  }
-  /**
-   * Record an audit log entry.
-   */
-  recordAudit(entry) {
-    if (!this.policy.auditLog?.enabled) return;
-    if (this.policy.auditLog.events && !this.policy.auditLog.events.includes(entry.event)) return;
-    const fullEntry = {
-      ...entry,
-      timestamp: (/* @__PURE__ */ new Date()).toISOString()
-    };
-    this.auditLog.push(fullEntry);
-    const dest = this.policy.auditLog.destination ?? "console";
-    if (dest === "console" || dest === "both") {
-      console.info("[AUDIT]", fullEntry.event, fullEntry.userId, fullEntry.resource ?? "");
-    }
-  }
-  /**
-   * Get audit log entries.
-   */
-  getAuditLog(filter) {
-    let entries = [...this.auditLog];
-    if (filter?.event) entries = entries.filter((e) => e.event === filter.event);
-    if (filter?.userId) entries = entries.filter((e) => e.userId === filter.userId);
-    if (filter?.since) entries = entries.filter((e) => e.timestamp >= filter.since);
-    return entries;
-  }
-  /**
-   * Apply data masking to a record.
-   */
-  maskRecord(record, userRoles = []) {
-    if (!this.policy.dataMasking?.rules?.length) return record;
-    const masked = { ...record };
-    const maskChar = this.policy.dataMasking.maskChar ?? "*";
-    for (const rule of this.policy.dataMasking.rules) {
-      if (!(rule.field in masked) || masked[rule.field] == null) continue;
-      if (rule.exemptRoles?.some((role) => userRoles.includes(role))) continue;
-      const value = String(masked[rule.field]);
-      switch (rule.strategy) {
-        case "full":
-          masked[rule.field] = maskChar.repeat(value.length);
-          break;
-        case "partial": {
-          const visible = rule.visibleChars ?? 4;
-          if (value.length <= visible) {
-            masked[rule.field] = maskChar.repeat(value.length);
-          } else {
-            masked[rule.field] = value.slice(0, visible) + maskChar.repeat(value.length - visible);
-          }
-          break;
-        }
-        case "hash":
-          masked[rule.field] = `[HASHED:${simpleHash(value)}]`;
-          break;
-        case "redact":
-          masked[rule.field] = "[REDACTED]";
-          break;
-      }
-    }
-    return masked;
-  }
-  /**
-   * Update the security policy.
-   */
-  updatePolicy(policy) {
-    this.policy = { ...this.policy, ...policy };
-  }
-  /**
-   * Get current security policy.
-   */
-  getPolicy() {
-    return { ...this.policy };
-  }
-};
-function simpleHash(str) {
-  let hash = 0;
-  for (let i = 0; i < str.length; i++) {
-    const char = str.charCodeAt(i);
-    hash = (hash << 5) - hash + char;
-    hash = hash & hash;
-  }
-  return Math.abs(hash).toString(36);
+// 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/studio.ts
-function createDefaultCanvasConfig(overrides) {
-  return {
-    width: 1200,
-    height: 800,
-    background: "grid",
-    gridSize: 8,
-    snapToGrid: true,
-    zoom: {
-      min: 0.25,
-      max: 3,
-      step: 0.1,
-      current: 1
-    },
-    panOffset: { x: 0, y: 0 },
-    showMinimap: false,
-    minimapPosition: "bottom-right",
-    ...overrides
-  };
+// src/metadata-error.ts
+function extractIssues(e) {
+  const issues = e?.issues;
+  return Array.isArray(issues) ? issues : [];
 }
-function snapToGrid(x, y, gridSize) {
-  return {
-    x: Math.round(x / gridSize) * gridSize,
-    y: Math.round(y / gridSize) * gridSize
-  };
+function formatMetadataIssue(i) {
+  return `\u2022 ${i.path && i.path.length > 0 ? i.path : "(root)"} \u2014 ${i.message}`;
 }
-function calculateAutoLayout(items, canvasWidth, padding = 40, gap = 40) {
-  const positions = [];
-  let currentX = padding;
-  let currentY = padding;
-  let rowMaxHeight = 0;
-  for (const item of items) {
-    if (currentX + item.width + padding > canvasWidth) {
-      currentX = padding;
-      currentY += rowMaxHeight + gap;
-      rowMaxHeight = 0;
-    }
-    positions.push({ id: item.id, x: currentX, y: currentY });
-    currentX += item.width + gap;
-    rowMaxHeight = Math.max(rowMaxHeight, item.height);
-  }
-  return positions;
+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
@@ -1473,6 +1856,15 @@ var FILTER_OPERATOR_ALIASES = {
   notin: "nin",
   nin: "nin",
   contains: "contains",
+  // Case-insensitive contains. A canonical `VIEW_FILTER_OPERATORS` member that
+  // arrived with `@objectstack/spec` 17.1.0 (objectui#5328), and an IDENTITY row
+  // like `contains` above: `icontains` is itself a member of
+  // `VALID_AST_OPERATORS`, so the spelling the author writes is the spelling the
+  // AST takes — nothing is translated and no case-sensitivity is lost.
+  // Declared rather than left to the `?? op` fall-through on the rule this
+  // table's test states: the AST gate accepting a spelling is not the driver
+  // compiling it into a WHERE clause.
+  icontains: "icontains",
   not_contains: "notcontains",
   notcontains: "notcontains",
   starts_with: "startswith",
@@ -1494,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.`
     );
@@ -1519,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) {
@@ -1533,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;
   });
@@ -1545,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;
@@ -1570,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") {
@@ -1632,22 +2149,134 @@ 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) {
+  constructor(surface, detail, serverCode) {
     super(
       `Analytics capability is not installed on this deployment \u2014 ${surface} is unavailable. Install @objectstack/service-analytics and mount AnalyticsServicePlugin to enable it.` + (detail ? ` (server said: ${detail})` : "")
     );
     __publicField(this, "code", "ANALYTICS_NOT_INSTALLED");
     /** The surface that was unavailable, for the message a host renders. */
     __publicField(this, "surface");
+    /**
+     * The server's own ADR-0112 code — the field this branch was chosen BY, when
+     * a producer named one (`NOT_IMPLEMENTED` from the mounted route with no
+     * service behind it, `ROUTE_NOT_FOUND` from the dispatcher when the route is
+     * not mounted at all). Absent for the no-code residual, where a bare
+     * transport 404/501 is all there was to read.
+     *
+     * Additive (objectui#5663): carried so a reader can audit that the headline
+     * and the quoted `detail` below came off the same answer.
+     */
+    __publicField(this, "serverCode");
     this.name = "AnalyticsNotInstalledError";
     this.surface = surface;
+    this.serverCode = serverCode;
   }
 };
 function isAnalyticsNotInstalledError(error) {
   if (!error || typeof error !== "object") return false;
   return error.code === "ANALYTICS_NOT_INSTALLED";
 }
+var AnalyticsDatasetNotFoundError = class extends Error {
+  constructor(opts) {
+    const subject = opts.datasetName ? `Dataset "${opts.datasetName}"` : "The requested dataset";
+    super(
+      `${subject} is not defined in this environment \u2014 the app that defines it is missing or out of date. Analytics itself is installed and answering, so the fix is to upgrade the installed app, not to install a server plugin.` + (opts.serverMessage ? ` (server said: ${opts.serverMessage})` : "")
+    );
+    __publicField(this, "code", "ANALYTICS_DATASET_NOT_FOUND");
+    /**
+     * The dataset this query asked for, taken from the REQUEST rather than parsed
+     * back out of the server's prose: the request is what we know for certain,
+     * and re-reading the name out of a message would make the headline depend on
+     * that message's WORDING — the coupling framework#5367 spent a whole issue
+     * removing from the producing route.
+     */
+    __publicField(this, "datasetName");
+    /** The server's own ADR-0112 code — the field this branch was chosen BY. */
+    __publicField(this, "serverCode");
+    /** The server's own message, quoted verbatim in the parenthetical. */
+    __publicField(this, "serverMessage");
+    this.name = "AnalyticsDatasetNotFoundError";
+    this.datasetName = opts.datasetName;
+    this.serverCode = opts.serverCode;
+    this.serverMessage = opts.serverMessage;
+  }
+};
+var AnalyticsUnauthenticatedError = class extends Error {
+  constructor(opts = {}) {
+    super(
+      "Analytics query refused: this session is not authenticated. Sign in again and retry \u2014 the request was refused before it ran, so it says nothing about whether the analytics capability is installed." + (opts.serverMessage ? ` (server said: ${opts.serverMessage})` : "")
+    );
+    __publicField(this, "code", "ANALYTICS_UNAUTHENTICATED");
+    /** The server's own ADR-0112 code — the field this branch was chosen BY. */
+    __publicField(this, "serverCode");
+    /** The server's own message, quoted verbatim in the parenthetical. */
+    __publicField(this, "serverMessage");
+    this.name = "AnalyticsUnauthenticatedError";
+    this.serverCode = opts.serverCode;
+    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;
+  const wrapped = flat.error && typeof flat.error === "object" ? flat.error : void 0;
+  const source = wrapped ?? flat;
+  const code = typeof source.code === "string" && source.code.length > 0 ? source.code : void 0;
+  const message = typeof source.message === "string" && source.message.length > 0 ? source.message : typeof flat.error === "string" && flat.error.length > 0 ? flat.error : void 0;
+  return { code, message };
+}
+var ANALYTICS_ABSENT_STATUSES = [404, 501];
 var AnalyticsQueryRejectedError = class extends Error {
   constructor(detail, serverCode) {
     super(
@@ -1660,15 +2289,48 @@ 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 : void 0;
+  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;
-  if (code === "VALIDATION_FAILED" || status === 400) return { kind: "rejected", code, message };
-  if (status === 404 || status === 501 || code === "NOT_IMPLEMENTED" || code === "ROUTE_NOT_FOUND") {
+  if (errorCodeIsAnyOf({ code }, ["NOT_IMPLEMENTED", "ROUTE_NOT_FOUND"])) {
     return { kind: "not-installed", code, message };
   }
+  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 === 401) return { kind: "unauthenticated", code, message };
+  }
   return { kind: "unknown", code, message };
 }
 var ConcurrentUpdateError = class extends Error {
@@ -1678,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) {
@@ -1688,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) => {
@@ -1705,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) {
@@ -1741,8 +2430,14 @@ function createQuietHttpLogger() {
     return false;
   };
   const logger = {
-    debug: (message, meta) => console.debug(message, meta ?? ""),
-    info: (message, meta) => console.info(message, meta ?? ""),
+    debug: (message, meta) => (
+      // eslint-disable-next-line no-console -- objectui#4029, see comment above
+      console.debug(message, meta ?? "")
+    ),
+    info: (message, meta) => (
+      // eslint-disable-next-line no-console -- objectui#4029, see comment above
+      console.info(message, meta ?? "")
+    ),
     warn: (message, meta) => console.warn(message, meta ?? ""),
     error: (message, error, meta) => {
       if (isExpected404(meta)) {
@@ -1755,12 +2450,87 @@ function createQuietHttpLogger() {
       console.error(formatHttpFailureMessage(message, meta) ?? message, error ?? "", meta ?? "");
     },
     fatal: (message, error, meta) => console.error(formatHttpFailureMessage(message, meta) ?? message, error ?? "", meta ?? ""),
+    // eslint-disable-next-line no-console -- objectui#4029, see comment above
     log: (message, ...args) => console.log(message, ...args),
     child: () => logger,
     withTrace: () => logger
   };
   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(",")}]`;
@@ -1793,15 +2563,48 @@ 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 isPersonalizationOverlayRow(item, spec) {
+  return item?.[VIEW_OVERLAY_MARKER] === true || spec?.[VIEW_OVERLAY_MARKER] === true;
+}
+var VIEW_OVERLAY_OWNED_KEYS = Object.freeze([
+  "rowHeight",
+  "sort",
+  "hiddenFields",
+  "columnState",
+  "inlineEdit"
+]);
+var VIEW_OVERLAY_IDENTITY_KEYS = Object.freeze([
+  "name",
+  "object",
+  "viewKind",
+  VIEW_OVERLAY_MARKER
+]);
+function narrowPersonalizationOverlay(row) {
+  if (!row || typeof row !== "object" || Array.isArray(row)) return row;
+  const item = row;
+  const spec = item.list ?? item;
+  if (!isPersonalizationOverlayRow(item, spec)) return row;
+  const narrowed = {};
+  for (const key of VIEW_OVERLAY_IDENTITY_KEYS) {
+    if (item[key] !== void 0) narrowed[key] = item[key];
+  }
+  for (const key of VIEW_OVERLAY_OWNED_KEYS) {
+    if (item[key] !== void 0) narrowed[key] = item[key];
+  }
+  return narrowed;
 }
 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;
@@ -1857,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).
@@ -1871,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
@@ -1880,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);
@@ -1888,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);
   }
   /**
@@ -2061,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
@@ -2094,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();
@@ -2200,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.
@@ -2233,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
       );
@@ -2247,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]
       });
@@ -2255,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) {
@@ -2269,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
@@ -2306,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).
    *
@@ -2363,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
           });
@@ -2410,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) {
@@ -2433,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) {
@@ -2534,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
@@ -2976,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;
     }
@@ -3028,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();
@@ -3058,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;
         }
       }
     }
@@ -3178,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
@@ -3366,25 +4271,94 @@ var ObjectStackAdapter = class {
     }
   }
   /**
-   * Persist a view definition for an object.
+   * Persist a toolbar-driven view config patch — density, column widths,
+   * sort, hidden columns, inline edit. Symmetric counterpart to
+   * {@link getView}: writes the row to the server metadata store via
+   * `client.meta.saveItem`, then invalidates the matching cache entry so the
+   * next {@link getView} reflects the new payload. Returns the persisted item
+   * when the server echoes it, otherwise undefined.
+   *
+   * Called from exactly ONE production site — `ObjectView`'s
+   * `persistViewPatch`, for the toolbar toggle — but that ONE call site
+   * fires for BOTH kinds of active tab: a code-defined **system** view (no
+   * row of its own yet) and a genuinely user-created **saved** view (already
+   * has a row — the toggle is editing ITS OWN definition, not laying an
+   * overlay on top of it). Which one a given call means is NOT re-derived
+   * here from the write's shape (objectui#4227's own lesson: shape inference
+   * on this namespace is exactly what let a system view masquerade as
+   * saved) — the caller already knows, via the same `isSavedViewId`
+   * classification that gates the switcher's readonly flag and its five
+   * mutating handlers, and passes it as {@link opts.isSavedView}.
    *
-   * Symmetric counterpart to {@link getView}: writes the view to the
-   * server metadata store via `client.meta.saveItem`, then invalidates
-   * the matching cache entry so the next {@link getView} reflects the
-   * new payload. Returns the persisted item when the server echoes it,
-   * otherwise undefined.
+   * - `isSavedView` false/omitted (system-view target, the common case and
+   *   the default for backward compatibility): stamps
+   *   {@link VIEW_OVERLAY_MARKER} so {@link listViews} excludes the row —
+   *   the original objectui#4227 fix.
+   * - `isSavedView` true: the marker is withheld. Stamping it here would
+   *   flag the saved view's OWN row as a personalization overlay, and
+   *   `listViews()` would exclude it on the very next read — the user's own
+   *   view would vanish from the switcher the moment they toggled its
+   *   density (objectui#4227 follow-up, PM review on PR #4713, measured:
+   *   `persistViewPatch` has no gate on which kind of tab is active, and
+   *   this method writes to the exact same `(type='view', name=viewId)` key
+   *   {@link createView}/the ADR-0034 `viewEnvelope` seam already used for
+   *   that view, so the write is an upsert onto the saved view's row, not a
+   *   new one).
    *
-   * Used by ObjectView for "live" toolbar persistence (density,
-   * column widths, sort, etc.) and by the View Config Panel for
-   * explicit saves.
+   * Per objectstack#7494's ruling, the overlay this writes (system-view
+   * case) is ORG-WIDE shared view settings, not a per-user preference — a
+   * true per-user scope is a parked v18 direction on the platform side.
    *
    * @param objectName - Object name (e.g. 'lead')
    * @param viewId - View identifier (e.g. 'all_leads')
    * @param config - Full view definition to persist
+   * @param opts.isSavedView - Whether `viewId` already names a saved view
+   *   (vs. a system view being personalized for the first time). Omit /
+   *   `false` for the default overlay-marking behavior.
    */
-  async updateViewConfig(objectName, viewId, config) {
+  /**
+   * [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 || {}, object: config?.object || objectName, name: viewId };
+    const merged = {
+      ...config || {},
+      object: config?.object || objectName,
+      name: viewId,
+      ...opts?.isSavedView ? {} : { [VIEW_OVERLAY_MARKER]: true }
+    };
     const result = await this.client.meta.saveItem(
       "view",
       viewId,
@@ -3405,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();
@@ -3423,23 +4433,42 @@ var ObjectStackAdapter = class {
         const spec = v.list ?? v;
         if (viewItemObjectName(v) !== objectName) return false;
         const viewKind = v.viewKind ?? spec?.viewKind;
-        return !(viewKind && FORM_FAMILY.has(viewKind));
+        if (viewKind && FORM_FAMILY.has(viewKind)) return false;
+        if (isPersonalizationOverlayRow(v, spec)) return false;
+        return true;
       }).map((v) => {
         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 [];
     }
   }
@@ -3458,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();
@@ -3472,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 [];
     }
   }
@@ -3698,7 +4764,7 @@ var ObjectStackAdapter = class {
     try {
       const cacheKey = `app:${appId}`;
       return await this.metadataCache.get(cacheKey, async () => {
-        const result = await this.client.meta.getItem("apps", appId);
+        const result = await this.client.meta.getItem("app", appId);
         if (result && result.item) return result.item;
         return result ?? null;
       });
@@ -3710,8 +4776,13 @@ var ObjectStackAdapter = class {
    * Ask the by-name meta app route WHY an app is not in this session's app list
    * (objectui#4252).
    *
-   * `GET /api/v1/meta/apps` is filtered per session server-side
-   * (`filterAppForUser`), so an app withheld by `requiredPermissions` and an app
+   * The app LIST is the generic metadata list route `GET /api/v1/meta/:type`,
+   * requested with the singular type segment `app` — the same address this
+   * method appends a name to below, and the one `MetadataProvider` reads its
+   * items from. The server filters that list per session in `filterAppForUser`
+   * (`packages/rest/src/rest-server.ts`, applied inside the `:type` list handler
+   * once the type segment resolves to `app`), so an app withheld by
+   * `requiredPermissions` and an app
    * that does not exist are byte-identical there: both are simply absent. A
    * console reading only that list has one fact and two conditions, and it
    * renders its copy for the wrong one — "it may still be publishing" over a
@@ -3721,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}
    *
@@ -3736,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";
     }
   }
   /**
@@ -3761,7 +4860,7 @@ var ObjectStackAdapter = class {
     try {
       const cacheKey = `page:${pageId}`;
       return await this.metadataCache.get(cacheKey, async () => {
-        const result = await this.client.meta.getItem("pages", pageId);
+        const result = await this.client.meta.getItem("page", pageId);
         if (result && result.item) return result.item;
         return result ?? null;
       });
@@ -3798,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();
@@ -3807,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;
@@ -3815,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);
@@ -3824,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;
@@ -3847,16 +4953,54 @@ 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);
       }
+      if (failure.kind === "unauthenticated") {
+        throw new AnalyticsUnauthenticatedError({
+          serverCode: failure.code,
+          serverMessage: failure.message
+        });
+      }
+      if (failure.kind === "cube-not-found") {
+        throw e;
+      }
       if (failure.kind === "not-installed") {
         this.warnAnalyticsCapabilityOnce(failure.message);
       }
       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
@@ -3930,14 +5074,42 @@ var ObjectStackAdapter = class {
       body: JSON.stringify(requestBody)
     });
     if (!res.ok) {
-      let detail = "";
+      let errBody;
       try {
-        const errBody = await res.json();
-        detail = errBody?.message || errBody?.error || JSON.stringify(errBody);
+        errBody = await res.json();
       } catch {
       }
-      if (res.status === 501 || res.status === 404) {
-        throw new AnalyticsNotInstalledError("POST /analytics/dataset/query", detail || void 0);
+      const { code: serverCode, message: serverMessage } = readAnalyticsErrorEnvelope(errBody);
+      const detail = serverMessage || (errBody === void 0 ? "" : JSON.stringify(errBody));
+      const surface = "POST /analytics/dataset/query";
+      const requestedDatasetName = typeof dataset === "string" ? dataset : typeof dataset?.name === "string" ? String(dataset.name) : void 0;
+      if (errorCodeIsAnyOf({ code: serverCode }, ["NOT_IMPLEMENTED", "ROUTE_NOT_FOUND"])) {
+        throw new AnalyticsNotInstalledError(surface, serverMessage, serverCode);
+      }
+      if (errorCodeIs({ code: serverCode }, "NOT_FOUND")) {
+        throw new AnalyticsDatasetNotFoundError({
+          datasetName: requestedDatasetName,
+          serverCode,
+          serverMessage
+        });
+      }
+      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);
+        }
+        if (res.status === 401) {
+          throw new AnalyticsUnauthenticatedError({ serverMessage });
+        }
       }
       throw new Error(`Dataset query failed: ${res.status} ${res.statusText}${detail ? ` \u2014 ${detail}` : ""}`);
     }
@@ -4071,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
       );
@@ -4113,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
       );
@@ -4196,31 +5370,47 @@ function createObjectStackAdapter(config) {
 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,
-  IntegrationManager,
+  META_ITEM_ABSENT_CODE,
   MalformedFilterError,
   MetadataClient,
   MetadataNotFoundError,
+  OBJECT_METADATA_TYPE,
   ObjectStackAdapter,
   ObjectStackError,
-  SecurityManager,
-  calculateAutoLayout,
+  RELATIONSHIP_TYPES_REQUIRING_REFERENCE,
+  UNRECOGNIZED_DROP_REASON,
+  UnlowerableAnalyticsFilterError,
+  UnloweredAggregateWhereError,
+  VIEW_CONFIG_CAPABILITY,
+  VIEW_OVERLAY_OWNED_KEYS,
+  ViewConfigPermissionDeniedError,
+  assertObjectMetadataWritable,
   classifyAnalyticsFailure,
+  classifyImportMappingsFailure,
+  classifyViewsFailure,
   clearSharedDiscoveryCache,
-  createDefaultCanvasConfig,
   createErrorFromResponse,
   createObjectStackAdapter,
   createObjectStackUserStateAdapter,
   createQuietHttpLogger,
+  extractDraftBody,
   formatHttpFailureMessage,
-  generateContractManifest,
+  formatMetadataError,
+  formatMetadataIssue,
   getSharedDiscovery,
   is404Error,
   isAnalyticsNotInstalledError,
@@ -4229,12 +5419,13 @@ export {
   isConcurrentUpdateError,
   isErrorType,
   isMalformedFilterError,
+  isMetaItemAbsentError,
   isObjectStackError,
+  isViewConfigPermissionDeniedError,
+  narrowPersonalizationOverlay,
   normaliseClientError,
   readSaveAdvisories,
   readTransactionalBatchCapability,
   serializeOrderBy,
-  snapToGrid,
-  validatePluginContract,
   viewItemObjectName
 };