@object-ui/data-objectstack 17.6.0 → 18.0.0

package/dist/index.js

@@ -4,6 +4,72 @@ 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 { ValidateDataIssueSchema } from "@objectstack/spec/api";
+import { stripReadDecorations as stripReadDecorations2 } from "@objectstack/spec/kernel";
+
+// src/metadata-client.ts
+import { FlowRegistrationSchema, 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(
+        `The object was not saved: 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\`, 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(
+      `The object was not saved: the field \`${name}\` is a \`${String(def.type)}\` and carries ${describeTarget(def.reference)}, so it names no object to link to. The server refuses the same document 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. Pick the target object, or change the field to a non-relationship type.`
+    );
+  }
+}
 
 // src/metadata-client.ts
 function readSaveAdvisories(body) {
@@ -16,6 +82,34 @@ 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";
   });
 }
+function readRegistrations(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return void 0;
+  const out = {};
+  for (const [name, verdict] of Object.entries(raw)) {
+    const parsed = FlowRegistrationSchema.safeParse(verdict);
+    if (parsed.success) out[name] = parsed.data;
+  }
+  return out;
+}
+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 +122,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 {
@@ -53,6 +157,26 @@ function isMetaItemEnvelope(value) {
   const env = value;
   return typeof env.type === "string" && typeof env.name === "string" && "item" in env;
 }
+var pendingReads = /* @__PURE__ */ new WeakMap();
+function pendingReadsOn(transport) {
+  let reads = pendingReads.get(transport);
+  if (!reads) {
+    reads = /* @__PURE__ */ new Map();
+    pendingReads.set(transport, reads);
+  }
+  return reads;
+}
+function handOut(entry) {
+  entry.waiting += 1;
+  return entry.read.then((value) => {
+    entry.waiting -= 1;
+    return entry.waiting === 0 ? value : ownCopy(value);
+  });
+}
+function ownCopy(value) {
+  if (value === null || typeof value !== "object") return value;
+  return typeof structuredClone === "function" ? structuredClone(value) : JSON.parse(JSON.stringify(value));
+}
 var MetadataClient = class _MetadataClient {
   constructor(config) {
     __publicField(this, "base");
@@ -60,7 +184,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);
@@ -103,34 +227,102 @@ var MetadataClient = class _MetadataClient {
       ...this.onSaveAdvisory ? { onSaveAdvisory: this.onSaveAdvisory } : {}
     });
   }
+  /**
+   * Share one in-flight GET among the callers asking the same method for the
+   * same URL with the same headers through the same transport (objectui#11797).
+   *
+   * Opening a Studio package mounts several readers that ask the same
+   * question at once, and each one sent its own request. The first call for a
+   * key sends `read()`; a call that arrives while it is pending waits for that
+   * request instead of sending another.
+   *
+   * ⛔ Not a response cache, deliberately — the rules `findOne` keeps on the
+   * data adapter (objectui#11699):
+   *  - the entry goes the moment the read settles, so a call made after an
+   *    answer always reaches the network (there is no reuse window: a client
+   *    cannot see every write that changes metadata, an agent's server-side
+   *    edits among them, and a window would answer the read after such a write
+   *    with the state from before it);
+   *  - a rejection reaches every caller already waiting and is not remembered;
+   *  - a write sent through the same transport drops every pending read when
+   *    it lands (see {@link sendWrite}), so a read asked after a save or a
+   *    publish is never answered by a request sent before it;
+   *  - every caller, the first one included, gets an answer no other caller
+   *    holds (see {@link handOut}).
+   */
+  shareRead(reader, url, read) {
+    const reads = pendingReadsOn(this.fetchImpl);
+    const key = JSON.stringify([reader, url, Object.entries(this.headers).sort(([a], [b]) => a.localeCompare(b))]);
+    let entry = reads.get(key);
+    if (!entry) {
+      const created = { read: read(), waiting: 0 };
+      reads.set(key, created);
+      const settle = () => {
+        if (reads.get(key) === created) reads.delete(key);
+      };
+      created.read.then(settle, settle);
+      entry = created;
+    }
+    return handOut(entry);
+  }
+  /**
+   * Send a write, then drop every read still pending on this transport
+   * (objectui#11797): a read on the wire when the write lands was asked before
+   * it, so a caller asking after the write must not join it. Dropped however
+   * the write ends — a refused or interrupted write may still have changed
+   * something. The callers already holding a pending read keep its answer.
+   */
+  async sendWrite(url, init) {
+    try {
+      return await this.fetchImpl(url, init);
+    } finally {
+      pendingReads.get(this.fetchImpl)?.clear();
+    }
+  }
   /** List all registered metadata types (returns the registry rows). */
   async listTypes() {
-    const res = await this.fetchImpl(this.base, { method: "GET", headers: this.headers, cache: "no-store" });
-    if (!res.ok) throw await parseError(res);
-    const data = await res.json();
-    if (Array.isArray(data)) return data;
-    if (data && Array.isArray(data.entries)) return data.entries;
-    if (data && Array.isArray(data.items)) return data.items;
-    if (data && Array.isArray(data.types)) {
-      return data.types.map((t) => ({ type: t }));
-    }
-    return [];
+    return this.shareRead("listTypes", this.base, async () => {
+      const res = await this.fetchImpl(this.base, { method: "GET", headers: this.headers, cache: "no-store" });
+      if (!res.ok) throw await parseError(res);
+      const data = await res.json();
+      if (Array.isArray(data)) return data;
+      if (data && Array.isArray(data.entries)) return data.entries;
+      if (data && Array.isArray(data.items)) return data.items;
+      if (data && Array.isArray(data.types)) {
+        return data.types.map((t) => ({ type: t }));
+      }
+      return [];
+    });
   }
   /** List items of a metadata type (e.g. `object`, `field`, `view`). */
   async list(type, options = {}) {
+    return (await this.listResponse(type, options)).items;
+  }
+  /**
+   * The same list read as {@link list}, with what the server serves beside
+   * the items (objectui#12349): today that is the automation engine's
+   * `registrations` on a `flow` list — see {@link MetadataListAnswer}.
+   *
+   * One request for both methods: `list` is this read with the items picked
+   * out, so a caller asking both at once shares one in-flight GET.
+   */
+  async listResponse(type, options = {}) {
     const params = [];
     if (options.packageId) params.push(`package=${encodeURIComponent(options.packageId)}`);
     if (this.previewDrafts) params.push("preview=draft");
     const qs = params.length ? `?${params.join("&")}` : "";
     const url = `${this.base}/${encodeURIComponent(type)}${qs}`;
-    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
-    if (!res.ok) throw await parseError(res);
-    const data = await res.json();
-    if (Array.isArray(data)) return data;
-    if (data && Array.isArray(data.items)) {
-      return data.items;
-    }
-    return [];
+    return this.shareRead("list", url, async () => {
+      const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
+      if (!res.ok) throw await parseError(res);
+      const data = await res.json();
+      if (Array.isArray(data)) return { items: data };
+      if (data && Array.isArray(data.items)) {
+        const registrations = readRegistrations(data.registrations);
+        return { items: data.items, ...registrations ? { registrations } : {} };
+      }
+      return { items: [] };
+    });
   }
   /**
    * List pending DRAFT items (ADR-0033) — what an AI authored but nobody
@@ -146,11 +338,13 @@ var MetadataClient = class _MetadataClient {
     if (options.type) params.push(`type=${encodeURIComponent(options.type)}`);
     const qs = params.length ? `?${params.join("&")}` : "";
     const url = `${this.base}/_drafts${qs}`;
-    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
-    if (!res.ok) throw await parseError(res);
-    const data = await res.json();
-    if (Array.isArray(data)) return data;
-    return data?.drafts ?? data?.data?.drafts ?? [];
+    return this.shareRead("listDrafts", url, async () => {
+      const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
+      if (!res.ok) throw await parseError(res);
+      const data = await res.json();
+      if (Array.isArray(data)) return data;
+      return data?.drafts ?? data?.data?.drafts ?? [];
+    });
   }
   /**
    * Fetch a single metadata item and return the response body EXACTLY as the
@@ -169,10 +363,12 @@ var MetadataClient = class _MetadataClient {
     if (options.packageId) params.push(`package=${encodeURIComponent(options.packageId)}`);
     const qs = params.length ? `?${params.join("&")}` : "";
     const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}${qs}`;
-    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
-    if (res.status === 404) return null;
-    if (!res.ok) throw await parseError(res);
-    return await res.json();
+    return this.shareRead("readItemResponse", url, async () => {
+      const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
+      if (res.status === 404) return null;
+      if (!res.ok) throw await parseError(res);
+      return await res.json();
+    });
   }
   /**
    * Get a single metadata item. Returns the unwrapped item CONTENT — the
@@ -214,15 +410,90 @@ 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.
+   *
+   * objectui#11799 — whether a draft exists is answered by the pending-drafts
+   * ledger first (see {@link draftLedgerMayHold}), and `?state=draft` is sent
+   * only when the ledger lists the name. The item read answers 404 when there
+   * is no draft, so opening every item in Studio used to log one error per
+   * item for an answer the ledger gives with a 200.
    */
   async getDraft(type, name, options = {}) {
+    if (!await this.draftLedgerMayHold(name)) return null;
     return this.readItemResponse(type, name, {
       state: "draft",
       ...options.packageId ? { packageId: options.packageId } : {}
     });
   }
+  /**
+   * Whether the pending-drafts ledger (`GET /meta/_drafts`) may hold a draft
+   * named `name` (objectui#11799).
+   *
+   * Read through {@link listDrafts}, the shared read objectui#11797 made: a
+   * question asked while a ledger read is pending waits for it, and a write
+   * through this transport drops it when the write lands ({@link sendWrite}),
+   * so a draft saved a moment ago is never reported absent by a read sent
+   * before the save.
+   *
+   * The WHOLE ledger, matched by name. The `?state=draft` read finds a row
+   * under either spelling of the type, and, when it names a package, that
+   * package's row or the package-less one. The ledger's `type` and `packageId`
+   * filters are exact, so a filtered ledger could miss a draft the item read
+   * would serve, and the editor would open the published body over a pending
+   * draft. Unfiltered, every miss here is a real absence; a same-name row of
+   * another type or package only costs the item read that was always sent.
+   *
+   * A ledger that cannot be read (403 without an authoring capability, 501 on
+   * a kernel without drafts, a network fault) is UNKNOWN, not empty: the item
+   * read is sent, as before.
+   */
+  async draftLedgerMayHold(name) {
+    let drafts;
+    try {
+      drafts = await this.listDrafts();
+    } catch {
+      return true;
+    }
+    return drafts.some((d) => d?.name === name);
+  }
+  /**
+   * 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,10 +506,17 @@ var MetadataClient = class _MetadataClient {
         `MetadataClient.save: name must be non-empty (type="${type}"). The PUT /meta/:type/:name route requires a name segment.`
       );
     }
+    if (options.ifMatch && options.ifNoneMatch) {
+      throw new Error(
+        `MetadataClient.save: ifMatch and ifNoneMatch are mutually exclusive (type="${type}", name="${name}"). Send ifMatch with the version you read, or ifNoneMatch: "*" when no row is there.`
+      );
+    }
+    assertObjectMetadataWritable(type, item, "MetadataClient.save");
     const params = [];
     if (options.force) params.push("force=true");
     if (options.mode === "draft") params.push("mode=draft");
     if (options.packageId) params.push(`package=${encodeURIComponent(options.packageId)}`);
+    if (options.surface) params.push(`surface=${encodeURIComponent(options.surface)}`);
     const qs = params.length ? `?${params.join("&")}` : "";
     const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}${qs}`;
     const headers = {
@@ -246,27 +524,20 @@ var MetadataClient = class _MetadataClient {
       "Content-Type": "application/json"
     };
     if (options.ifMatch) headers["If-Match"] = options.ifMatch;
-    const res = await this.fetchImpl(url, {
+    if (options.ifNoneMatch) headers["If-None-Match"] = options.ifNoneMatch;
+    const res = await this.sendWrite(url, {
       method: "PUT",
       headers,
       body: JSON.stringify(item)
     });
     if (!res.ok) throw await parseError(res);
     const body = await res.json();
-    if (this.onSaveAdvisory) {
-      try {
-        const advisories = readSaveAdvisories(body);
-        if (advisories.length > 0) {
-          this.onSaveAdvisory({
-            type,
-            name,
-            mode: options.mode === "draft" ? "draft" : "publish",
-            advisories
-          });
-        }
-      } catch {
-      }
-    }
+    this.emitAdvisories(body, {
+      type,
+      name,
+      door: "save",
+      mode: options.mode === "draft" ? "draft" : "publish"
+    });
     return body;
   }
   /**
@@ -280,18 +551,178 @@ 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.
+   *
+   * ## The bundle member (objectui#12402)
+   *
+   * Pass `member` to publish one member of a type whose identity is a pair
+   * (today only `email_template`, `(name, locale)`), sent as `?member=` — the
+   * selector the by-name doors read since objectstack `038d4c958`, and the
+   * value a `GET /meta/_drafts` row carries as `member`. A publish that names
+   * none promotes the CANONICAL member's draft, so two languages of one
+   * template drafted outside a package cannot both be published by name
+   * without it. The parameter is OMITTED, never sent empty, when the caller
+   * has no member: the door refuses a blank selector, and refuses any
+   * selector on a type with no members.
    */
-  async publishDraft(type, name) {
-    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/publish`;
-    const res = await this.fetchImpl(url, {
+  async publishDraft(type, name, options = {}) {
+    const params = [];
+    if (options.member) params.push(`member=${encodeURIComponent(options.member)}`);
+    const qs = params.length ? `?${params.join("&")}` : "";
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/publish${qs}`;
+    const res = await this.sendWrite(url, {
       method: "POST",
       headers: { ...this.headers, "Content-Type": "application/json", Accept: "application/json" },
       body: "{}"
     });
     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,
+      // objectui#12413 — the member this publish named, under the same rule as
+      // the query parameter above: present only when the caller had one.
+      ...options.member ? { member: options.member } : {},
+      door: "publish",
+      mode: "publish"
+    });
+    return body;
+  }
+  /**
+   * Publish EVERY pending draft bound to one package — Studio's "publish whole
+   * app" door, `POST /api/v1/packages/:id/publish-drafts` (ADR-0033; the route
+   * that orders structure-before-seeds server-side and runs the ADR-0038 L3
+   * runtime probes).
+   *
+   * ## Why it is expressed here at all (`ce986aafc`)
+   *
+   * It was not, and that was the defect. Two app-shell call sites fired this
+   * route with a bare `fetch` / a page-private `apiJson`, outside the seam that
+   * covers every other metadata write — so when objectstack#9343 landed and the
+   * server began sending per-draft advisories, the author publishing a whole
+   * app was told nothing, while the SAME button's client-side capability lint
+   * still raised a toast. A door that cannot report is not a door the gate can
+   * reach, however loudly the server speaks.
+   *
+   * ## What it reports, and what it refuses to invent
+   *
+   * `PublishPackageDraftsResponseSchema` declares `advisories` on EACH
+   * `published[]` element — objectstack#9343's ruled shape, the same element
+   * type and the same omitted-when-empty discipline as the single-item door,
+   * and explicitly not a parallel top-level map. So this method emits one
+   * {@link MetadataSaveAdvisoryEvent} per advised element, each naming that
+   * element's own `type` / `name`, through the same sink, event and renderer
+   * the save and single-item publish doors use.
+   *
+   * ⛔ It renders only what the server sent where the schema says it sits:
+   *
+   * - `advisories` is read off the element, by the one shared reader, which
+   *   drops anything that is not a complete finding.
+   * - An element that does not carry the `type` and `name` the schema states as
+   *   REQUIRED is skipped rather than reported under invented identity — the
+   *   event names the item the author has to go fix, and an event that cannot
+   *   name it truthfully is worse than silence.
+   * - Nothing is derived, counted or summarised from the batch: no advisory
+   *   exists here that the server did not put in the body.
+   *
+   * ## The failure shapes stay the callers'
+   *
+   * Non-2xx throws {@link MetadataError}, like every other method. A 2xx is
+   * RETURNED unexamined — `success: false` is not a failure on this route
+   * (`outcome: 'nothing_to_publish'` answers it too, and the spec's own text
+   * says to read `outcome`, not the boolean), and the two callers have their
+   * own, different rules for the refusal and rolled-back cases. Deciding that
+   * here would change behaviour this card is not about.
+   *
+   * ## The opt-in backfill (objectui#12929)
+   *
+   * `options.backfill` is sent as the body's `backfill` key, as given, and only
+   * when the caller passes one ({@link MetadataPublishPackageDraftsOptions}).
+   * Without it the body is `{}`, byte for byte what every caller sent before,
+   * so a caller that names nothing writes nothing into existing rows. The
+   * receipt is `backfillApplied` on the returned body, unexamined like the rest
+   * of a 2xx: one element per named field with the rows written, and `error`
+   * on a field that stopped short (the publish itself stands).
+   */
+  async publishPackageDrafts(packageId, options = {}) {
+    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.sendWrite(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: JSON.stringify(options.backfill !== void 0 ? { backfill: options.backfill } : {})
+    });
+    if (!res.ok) throw await parseError(res);
+    const body = unwrapDispatcherEnvelope(await res.json().catch(() => ({})));
+    for (const element of Array.isArray(body.published) ? body.published : []) {
+      if (!element || typeof element !== "object") continue;
+      const { type, name } = element;
+      if (typeof type !== "string" || typeof name !== "string") continue;
+      this.emitAdvisories(element, { type, name, door: "publish", mode: "publish" });
+    }
+    return body;
   }
   /**
    * Get the 3-state layered view of a metadata item: `code` (the packaged
@@ -333,7 +764,7 @@ var MetadataClient = class _MetadataClient {
     }
     if (!res.ok) throw await parseError(res);
     const body = await res.json();
-    const hasEnvelope = body && ("code" in body || "overlay" in body || "effective" in body);
+    const hasEnvelope = typeof body === "object" && body !== null && ("code" in body || "overlay" in body || "effective" in body);
     if (!hasEnvelope) {
       return {
         code: null,
@@ -342,14 +773,34 @@ var MetadataClient = class _MetadataClient {
         effective: body
       };
     }
+    const parsed = GetMetaItemLayeredResponseSchema.safeParse(body);
+    if (parsed.success) {
+      const envelope = parsed.data;
+      return {
+        code: envelope.code ?? null,
+        overlay: envelope.overlay ?? null,
+        overlayScope: envelope.overlayScope,
+        effective: envelope.effective ?? null,
+        ...body._diagnostics ? { _diagnostics: body._diagnostics } : {},
+        lock: envelope.lock,
+        ...envelope.lockReason !== void 0 ? { lockReason: envelope.lockReason } : {},
+        ...envelope.lockSource !== void 0 ? { lockSource: envelope.lockSource } : {},
+        ...envelope.lockDocsUrl !== void 0 ? { lockDocsUrl: envelope.lockDocsUrl } : {},
+        ...envelope.provenance !== void 0 ? { provenance: envelope.provenance } : {},
+        ...envelope.packageId !== void 0 ? { packageId: envelope.packageId } : {},
+        ...envelope.packageVersion !== void 0 ? { packageVersion: envelope.packageVersion } : {},
+        editable: envelope.editable,
+        deletable: envelope.deletable,
+        resettable: envelope.resettable
+      };
+    }
+    const unrecognized = unrecognizedEnvelopeKeys(body);
     return {
       code: body.code ?? null,
       overlay: body.overlay ?? null,
       overlayScope: body.overlayScope ?? null,
       effective: body.effective ?? null,
       ...body._diagnostics ? { _diagnostics: body._diagnostics } : {},
-      // ADR-0010 Phase 4 — pass through the metadata-protection envelope so
-      // the editor can render lock affordances without a second round trip.
       ...body.lock !== void 0 ? { lock: body.lock } : {},
       ...body.lockReason !== void 0 ? { lockReason: body.lockReason } : {},
       ...body.lockSource !== void 0 ? { lockSource: body.lockSource } : {},
@@ -359,7 +810,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 } : {}
     };
   }
   /**
@@ -410,13 +862,22 @@ var MetadataClient = class _MetadataClient {
    * Idempotent: returns the result even when no overlay row existed.
    * Pass `state: 'draft'` to discard the pending draft only (keeps the
    * published overlay intact) — useful for a Studio "Discard draft" button.
+   *
+   * Pass `packageId` to name the package whose row the delete removes, sent
+   * as `?package=`. A delete that names none addresses the one package that
+   * holds the item; when two or more packages hold it the door refuses it
+   * `409 RESOURCE_CONFLICT`, deletes nothing, and names `?package=` as the
+   * remedy. That refusal is thrown like any other {@link MetadataError}.
    */
   async reset(type, name, options = {}) {
-    const qs = options.state === "draft" ? "?state=draft" : "";
+    const params = [];
+    if (options.state === "draft") params.push("state=draft");
+    if (options.packageId) params.push(`package=${encodeURIComponent(options.packageId)}`);
+    const qs = params.length ? `?${params.join("&")}` : "";
     const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}${qs}`;
     const headers = { ...this.headers };
     if (options.ifMatch) headers["If-Match"] = options.ifMatch;
-    const res = await this.fetchImpl(url, { method: "DELETE", headers });
+    const res = await this.sendWrite(url, { method: "DELETE", headers });
     if (!res.ok) throw await parseError(res);
     return await res.json();
   }
@@ -426,20 +887,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"
     };
-    const res = await this.fetchImpl(url, {
+    const res = await this.sendWrite(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`).
@@ -455,7 +925,7 @@ var MetadataClient = class _MetadataClient {
       ...this.headers,
       "Content-Type": "application/json"
     };
-    const res = await this.fetchImpl(url, {
+    const res = await this.sendWrite(url, {
       method: "POST",
       headers,
       body: JSON.stringify({
@@ -534,15 +1004,38 @@ function errorCodeIsAnyOf(err, codes) {
 }
 
 // ../core/src/utils/filter-converter.ts
-import { normalizeFilterOperator } from "@objectstack/spec/ui";
+import {
+  normalizeFilterOperator,
+  VIEW_FILTER_OPERATORS,
+  VIEW_FILTER_LIST_VALUE_OPERATORS,
+  VIEW_FILTER_PAIR_VALUE_OPERATORS
+} from "@objectstack/spec/ui";
+import { isAcceptedFilterComparand, ACCEPTED_FILTER_COMPARAND_TYPES_SENTENCE } from "@objectstack/spec/data";
+
+// ../core/src/utils/text-comparand.ts
+import { isRefusedTextComparand, textComparandRefusalReason } from "@objectstack/spec/data";
+
+// ../core/src/utils/filter-converter.ts
 var FilterOperatorError = class extends Error {
-  constructor(message) {
+  constructor(message, subject) {
     super(message);
     __publicField(this, "code", "INVALID_FILTER");
     __publicField(this, "httpStatus", 400);
+    /** @see FilterRefusalSubject */
+    __publicField(this, "operator");
+    /** @see FilterRefusalSubject */
+    __publicField(this, "field");
     this.name = "FilterOperatorError";
+    this.operator = subject?.operator;
+    this.field = subject?.field;
   }
 };
+var RETIRED_OPERATOR_ALIASES = {
+  "$notin": "$nin",
+  "$notcontains": "$notContains",
+  "$startswith": "$startsWith",
+  "$endswith": "$endsWith"
+};
 function convertOperatorToAST(operator) {
   const operatorMap = {
     "$eq": "=",
@@ -553,27 +1046,148 @@ function convertOperatorToAST(operator) {
     "$lte": "<=",
     "$in": "in",
     "$nin": "nin",
-    "$notin": "nin",
     "$between": "between",
     "$contains": "contains",
     "$notContains": "notcontains",
-    "$notcontains": "notcontains",
     "$startsWith": "startswith",
-    "$startswith": "startswith",
     "$endsWith": "endswith",
-    "$endswith": "endswith"
+    // Case-insensitive contains. A canonical `FILTER_OPERATORS` member that
+    // `ValueDataSource` executes and `FilterConditionField` emits (for its
+    // `icontains` builder row — spelled `containsCaseInsensitive` until
+    // objectui#9306), while this map refused it with the
+    // generic unknown-operator paragraph — so ONE authored filter selected rows
+    // through the in-memory matcher and 400'd on the ObjectStack lowering path
+    // (objectui#8976). The other direction of the same split objectui#8568 fixed:
+    // there the map was MORE tolerant than the matcher, here it was LESS tolerant
+    // than the contract. Restored by aligning the map with the spec, per AGENTS.md
+    // #0 — not by removing the operator from the builder, which the spec declares.
+    //
+    // The VALUE is an IDENTITY, and that is not a typo: `icontains` is itself a
+    // member of the spec's `VALID_AST_OPERATORS`, so unlike its camelCase siblings
+    // above there is no case to squash. Same identity row, for the same stated
+    // reason, that `FILTER_OPERATOR_ALIASES` carries in
+    // `packages/data-objectstack/src/index.ts`.
+    "$icontains": "icontains"
   };
   return operatorMap[operator] || null;
 }
+var AST_LOGIC_KEYWORD = {
+  $and: "and",
+  $or: "or"
+};
+function lowerLogicalGroup(field, keyword, value) {
+  if (!Array.isArray(value)) {
+    throw new FilterOperatorError(
+      `[ObjectUI] The '${field}' filter combinator takes an ARRAY of conditions. Received ${typeof value === "object" ? "an object" : typeof value}: ${JSON.stringify(value)}. Spec: FilterCondition declares '${field}?: FilterCondition[]' (data/filter.zod.ts).`,
+      { operator: field }
+    );
+  }
+  if (value.length === 0) {
+    return keyword === "and" ? void 0 : falseIdentityLeaf(field, value);
+  }
+  const children = [];
+  let absorbed = false;
+  for (const child of value) {
+    if (child === null || typeof child !== "object" || Array.isArray(child)) {
+      throw new FilterOperatorError(
+        `[ObjectUI] Every member of '${field}' must be a filter condition OBJECT. Received ${JSON.stringify(child)}. Spec: FilterCondition declares '${field}?: FilterCondition[]' (data/filter.zod.ts).`,
+        { operator: field }
+      );
+    }
+    const lowered = convertFiltersToAST(child);
+    if (!Array.isArray(lowered)) {
+      if (keyword === "or") absorbed = true;
+      continue;
+    }
+    children.push(lowered);
+  }
+  if (absorbed) return void 0;
+  if (children.length === 0) return void 0;
+  return [keyword, ...children];
+}
+function falseIdentityLeaf(field, value) {
+  return [field, "=", value];
+}
+function isOperatorMap(value) {
+  const proto = Object.getPrototypeOf(value);
+  return proto === null || proto === Object.prototype || Object.getPrototypeOf(proto) === null;
+}
+function describeExoticComparand(value) {
+  let name;
+  let text2;
+  try {
+    const proto = Object.getPrototypeOf(value);
+    name = proto?.constructor?.name;
+  } catch {
+    name = void 0;
+  }
+  if (typeof name !== "string" || name === "") return "an object of an unrecognised type";
+  try {
+    text2 = String(value);
+  } catch {
+    text2 = void 0;
+  }
+  return text2 && text2 !== `[object ${name}]` ? `a ${name} instance (${text2})` : `a ${name} instance`;
+}
+function refuseTextComparand(field, operator, target) {
+  const ported = `It is refused here rather than lowered onto the wire (objectui#9001; ported from ValueDataSource's refuseTextComparand, objectui#8748).`;
+  throw new FilterOperatorError(
+    `[ObjectUI] The ${textComparandRefusalReason(field, operator, target)}. ${ported}`,
+    { operator, field }
+  );
+}
+function refuseEmptyOperatorMap(field) {
+  throw new FilterOperatorError(
+    `[ObjectUI] The filter on field '${field}' is an EMPTY operator map \u2014 { ${field}: {} } names the field and no operator. It cannot be lowered: the ObjectQL filter AST has no node for a field with zero operators, and '@objectstack/spec' ruled the shape REJECTED wherever it appears (objectstack#5240, recorded on FilterConditionSchema). It is refused here rather than dropped: beside a key that lowers, the '${field}' condition used to vanish from the filter and silently WIDEN the result set (objectui#10788), and alone it was handed back as the caller's object, which reached the wire as ?${field}=[object Object] on one route and as a filter the server refuses on the other (objectui#9164). Choose an operator \u2014 { ${field}: { $eq: ... } }, { ${field}: { $in: [...] } }, { ${field}: { $null: true } } \u2014 or remove the key.`,
+    { field }
+  );
+}
 function convertFiltersToAST(filter) {
   const conditions = [];
+  let trueIdentityGroups = 0;
+  let skippedNullKeys = 0;
   for (const [field, value] of Object.entries(filter)) {
-    if (value === null || value === void 0) continue;
+    if (value === null || value === void 0) {
+      skippedNullKeys += 1;
+      continue;
+    }
+    const logicKeyword = AST_LOGIC_KEYWORD[field];
+    if (logicKeyword) {
+      const group = lowerLogicalGroup(field, logicKeyword, value);
+      if (group !== void 0) conditions.push(group);
+      else trueIdentityGroups += 1;
+      continue;
+    }
+    if (field === "$not") {
+      throw new FilterOperatorError(
+        `[ObjectUI] The '$not' filter combinator cannot be lowered to the ObjectQL filter AST. '@objectstack/spec' declares it on FilterCondition, but the AST this layer emits has no negation keyword (FILTER_ARRAY_LOGIC_KEYWORDS is ['and', 'or']), and rewriting the negation inward is not available either \u2014 'startswith', 'endswith', 'between' and 'icontains' have no negated counterpart in VALID_AST_OPERATORS, so the rewrite would be silently partial. Express the negation with a negated operator instead ($ne, $nin, $notContains); note those follow each operator's own answer for a missing value rather than $not's NULL-safe rule (objectstack#5146). Value: ${JSON.stringify(value)}.`,
+        { operator: "$not" }
+      );
+    }
+    if (Array.isArray(value)) {
+      throw new FilterOperatorError(
+        `[ObjectUI] The filter on field '${field}' carries a bare ARRAY as its equality comparand: ${JSON.stringify(value)}. It cannot be lowered: the ObjectQL filter AST has no array-equality node, so the lowered node [${field}, '=', [...]] is refused by @objectstack/driver-sql (400 INVALID_FILTER) and matches no row in the in-memory matchers \u2014 it can never select anything. It is deliberately NOT read as membership here: { ${field}: [...] } and { ${field}: { $in: [...] } } are different statements, and guessing the second from the first would silently change which rows a stored view returns (objectui#8530; the same ruling objectui#8514 applied one layer down). Spell membership as { ${field}: { $in: [...] } }, its negation as { ${field}: { $nin: [...] } }, or a range as { ${field}: { $between: [min, max] } }.`,
+        { field }
+      );
+    }
     if (typeof value === "object" && !Array.isArray(value)) {
-      for (const [operator, operatorValue] of Object.entries(value)) {
+      if (isAcceptedFilterComparand(value)) {
+        conditions.push([field, "=", value]);
+        continue;
+      }
+      if (!isOperatorMap(value)) {
+        throw new FilterOperatorError(
+          `[ObjectUI] The filter on field '${field}' carries ${describeExoticComparand(value)} in comparand position. '@objectstack/spec' does not accept it: a comparison value must be ${ACCEPTED_FILTER_COMPARAND_TYPES_SENTENCE} (ACCEPTED_FILTER_COMPARAND_TYPES), so isAcceptedFilterComparand is false for it and normalizeFilterComparandTypes answers 400 INVALID_FILTER \u2014 "which no driver can compare". It is not an operator map either: only a plain object can be one, so until objectui#8567 this value was read as ZERO operators and the '${field}' condition was dropped from the filter entirely, silently WIDENING the result set. Spell a text match as { ${field}: { $contains: '...' } } ($startsWith / $endsWith; a pattern itself has no operator here, see the $regex refusal), a membership test as { ${field}: { $in: [...] } }, and a date bound as { ${field}: { $gte: new Date(...) } }.`,
+          { field }
+        );
+      }
+      const operatorEntries = Object.entries(value);
+      if (operatorEntries.length === 0) refuseEmptyOperatorMap(field);
+      for (const [operator, operatorValue] of operatorEntries) {
         if (operator === "$regex") {
           throw new FilterOperatorError(
-            `[ObjectUI] The '$regex' filter operator is not supported. It used to be converted to 'contains', which matches a literal substring rather than a pattern \u2014 a different result, not a degraded one. Field: '${field}', Value: ${JSON.stringify(operatorValue)}. Use $contains, $startsWith or $endsWith.`
+            `[ObjectUI] The '$regex' filter operator is not supported. It used to be converted to 'contains', which matches a literal substring rather than a pattern \u2014 a different result, not a degraded one. Field: '${field}', Value: ${JSON.stringify(operatorValue)}. Use $contains for a case-sensitive substring, $icontains for a case-insensitive one, or $startsWith / $endsWith.`,
+            { operator: "$regex", field }
           );
         }
         if (operator === "$null") {
@@ -584,12 +1198,33 @@ function convertFiltersToAST(filter) {
           conditions.push([field, operatorValue ? "is_not_null" : "is_null", true]);
           continue;
         }
+        if (operator === "$empty") {
+          if (operatorValue !== true && operatorValue !== false) {
+            throw new FilterOperatorError(
+              `[ObjectUI] The '$empty' filter operator on field '${field}' takes a boolean flag (true or false); received ${JSON.stringify(operatorValue) ?? String(operatorValue)}. Write { ${field}: { $empty: true } } for an empty value, or { ${field}: { $empty: false } } for a non-empty one.`,
+              { operator: "$empty", field }
+            );
+          }
+          conditions.push([field, operatorValue ? "is_empty" : "is_not_empty", true]);
+          continue;
+        }
         const astOperator = convertOperatorToAST(operator);
         if (astOperator) {
+          if (astOperator === "icontains" && isRefusedTextComparand(operatorValue)) {
+            refuseTextComparand(field, operator, operatorValue);
+          }
           conditions.push([field, astOperator, operatorValue]);
         } else {
+          const canonical = RETIRED_OPERATOR_ALIASES[operator];
+          if (canonical) {
+            throw new FilterOperatorError(
+              `[ObjectUI] The '${operator}' filter operator is retired. Write '${canonical}' instead \u2014 the canonical spelling '@objectstack/spec' declares in FILTER_OPERATORS (data/filter.zod.ts). The operator itself is unchanged; only the key is renamed. Field: '${field}', Value: ${JSON.stringify(operatorValue)}. It used to be accepted here as a lowercase alias while the in-memory matcher refused it, so the same filter selected rows through one data source and none through the other (objectui#8568).`,
+              { operator, field }
+            );
+          }
           throw new FilterOperatorError(
-            `[ObjectUI] Unknown filter operator '${operator}' for field '${field}'. Supported operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $between, $contains, $notContains, $startsWith, $endsWith, $null, $exists. If you need exact object matching, use the value directly without an operator.`
+            `[ObjectUI] Unknown filter operator '${operator}' for field '${field}'. Supported operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $between, $contains, $notContains, $startsWith, $endsWith, $icontains, $null, $exists, $empty. If you need exact object matching, use the value directly without an operator.`,
+            { operator, field }
           );
         }
       }
@@ -598,6 +1233,13 @@ function convertFiltersToAST(filter) {
     }
   }
   if (conditions.length === 0) {
+    const keysTheLoopProcessed = Object.keys(filter).length - skippedNullKeys;
+    if (trueIdentityGroups > 0 && trueIdentityGroups === keysTheLoopProcessed) {
+      return void 0;
+    }
+    if (skippedNullKeys > 0 && skippedNullKeys === Object.keys(filter).length) {
+      return void 0;
+    }
     return filter;
   }
   if (conditions.length === 1) {
@@ -605,6 +1247,52 @@ function convertFiltersToAST(filter) {
   }
   return ["and", ...conditions];
 }
+var ARRAY_VALUED_VIEW_OPERATORS = /* @__PURE__ */ new Set([
+  ...VIEW_FILTER_LIST_VALUE_OPERATORS,
+  ...VIEW_FILTER_PAIR_VALUE_OPERATORS
+]);
+var KNOWN_VIEW_OPERATORS = new Set(VIEW_FILTER_OPERATORS);
+
+// ../core/src/utils/column-sortability.ts
+import {
+  FIELD_UNSORTABLE_VIRTUAL_TYPE,
+  FIELD_SORTABLE_UNPROVISIONED_ANCHOR
+} from "@objectstack/spec/api";
+var OBJECT_SORTABILITY_KEY = /* @__PURE__ */ Symbol.for("objectui.objectSortability");
+function asFieldSortability(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const sortable = value.sortable;
+  if (typeof sortable !== "boolean") return void 0;
+  const reason = value.reason;
+  const caveat = value.caveat;
+  return {
+    sortable,
+    ...typeof reason === "string" ? { reason } : {},
+    ...typeof caveat === "string" ? { caveat } : {}
+  };
+}
+function normalizeObjectSortability(served) {
+  if (!served || typeof served !== "object" || Array.isArray(served)) return void 0;
+  const rawFields = served.fields;
+  if (!rawFields || typeof rawFields !== "object" || Array.isArray(rawFields)) return void 0;
+  const fields = {};
+  for (const [name, entry] of Object.entries(rawFields)) {
+    const verdict = asFieldSortability(entry);
+    if (verdict) fields[name] = verdict;
+  }
+  return { fields };
+}
+function attachObjectSortability(schema, served) {
+  const projection = normalizeObjectSortability(served);
+  if (!projection || !schema || typeof schema !== "object") return schema;
+  Object.defineProperty(schema, OBJECT_SORTABILITY_KEY, {
+    value: projection,
+    enumerable: false,
+    configurable: true,
+    writable: true
+  });
+  return schema;
+}
 
 // ../core/src/adapters/batchTransaction.ts
 function idOf(rec) {
@@ -673,20 +1361,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;
 }
 
@@ -739,21 +1550,54 @@ var MetadataCache = class {
         this.cache.delete(key);
       }
     }
+    return this.load(key, fetcher);
+  }
+  /**
+   * Join the read in flight for `key`, or start one, and never answer from the
+   * settled entry: a caller of this always gets an answer from a request that
+   * was on the wire when it asked.
+   *
+   * objectui#13044. This is the door for a caller whose own contract is "ask
+   * the server", which should still not put a second identical request on the
+   * wire while one is already there.
+   *
+   * objectui#13057. The landing is stored, exactly as one {@link get} started
+   * would store it, so a later {@link get} for `key` may be answered from it.
+   * The caller asked the server; a reader that may be served what the cache
+   * already holds is served the answer that caller just received.
+   */
+  share(key, fetcher) {
+    return this.load(key, fetcher);
+  }
+  /**
+   * The in-flight half of {@link get} and {@link share}: join the request in
+   * flight for `key`, or start one.
+   *
+   * A landing is stored, and its in-flight entry cleared, only
+   * while it is still the request registered for `key` (objectui#13044). {@link invalidate}
+   * and {@link clear} detach the request in flight, so a request sent before an
+   * invalidation can neither answer a caller who asks after it nor write its
+   * answer over a newer one.
+   */
+  load(key, fetcher) {
     const existing = this.inflight.get(key);
     if (existing) {
       this.stats.coalesced++;
       return existing;
     }
     this.stats.misses++;
-    const promise = (async () => {
+    const self = {};
+    const run = async () => {
       try {
         const data = await fetcher();
-        this.set(key, data);
+        if (this.inflight.get(key) === self.promise) this.set(key, data);
         return data;
       } finally {
-        this.inflight.delete(key);
+        if (this.inflight.get(key) === self.promise) this.inflight.delete(key);
       }
-    })();
+    };
+    const promise = run();
+    self.promise = promise;
     this.inflight.set(key, promise);
     return promise;
   }
@@ -801,8 +1645,10 @@ var MetadataCache = class {
   invalidate(key) {
     if (key) {
       this.cache.delete(key);
+      this.inflight.delete(key);
     } else {
       this.cache.clear();
+      this.inflight.clear();
     }
   }
   /**
@@ -872,6 +1718,21 @@ var MetadataCache = class {
   }
 };
 
+// src/metadata-error.ts
+function extractIssues(e) {
+  const issues = e?.issues;
+  return Array.isArray(issues) ? issues : [];
+}
+function formatMetadataIssue(i) {
+  return `\u2022 ${i.path && i.path.length > 0 ? i.path : "(root)"} \u2014 ${i.message}`;
+}
+function formatMetadataError(e) {
+  const issues = extractIssues(e);
+  if (issues.length > 0) return issues.map(formatMetadataIssue).join("\n");
+  const err = e;
+  return err?.message ?? String(e);
+}
+
 // src/errors.ts
 var ObjectStackError = class extends Error {
   /**
@@ -1059,53 +1920,88 @@ function isErrorType(error, errorClass) {
   return error instanceof errorClass;
 }
 
+// src/error-envelope.ts
+function readErrorEnvelope(body) {
+  if (!body || typeof body !== "object") return {};
+  const env = body;
+  const nested = env.error && typeof env.error === "object" ? env.error : void 0;
+  const reading = {};
+  const message = text(nested?.message) ?? text(env.message) ?? text(env.error);
+  if (message !== void 0) reading.message = message;
+  const code = present(env.code) ?? present(nested?.code);
+  if (code !== void 0) reading.code = code;
+  return reading;
+}
+function text(value) {
+  return typeof value === "string" && value.trim() !== "" ? value : void 0;
+}
+function present(value) {
+  return typeof value === "string" ? value : void 0;
+}
+
 // src/userState.ts
 var DEFAULT_RESOURCE = "sys_user_preference";
-function createObjectStackUserStateAdapter(options) {
-  const {
-    dataSource,
-    userId,
-    key,
-    resource = DEFAULT_RESOURCE,
-    onError = () => {
+var PREFERENCE_FAMILY_ROW_LIMIT = 200;
+function preferenceQuery(userId, keys, prefixes = []) {
+  if (prefixes.length === 0) {
+    if (keys.length === 1) {
+      return { $filter: { user_id: userId, key: keys[0] }, $top: 1 };
     }
-  } = options;
+    return { $filter: { user_id: userId, key: { $in: [...keys] } }, $top: keys.length };
+  }
+  const arms = [];
+  if (keys.length === 1) arms.push({ key: keys[0] });
+  else if (keys.length > 1) arms.push({ key: { $in: [...keys] } });
+  for (const prefix of prefixes) arms.push({ key: { $startsWith: prefix } });
+  return {
+    $filter: { user_id: userId, ...arms.length === 1 ? arms[0] : { $or: arms } },
+    $top: keys.length + prefixes.length * PREFERENCE_FAMILY_ROW_LIMIT
+  };
+}
+var openReads = /* @__PURE__ */ new WeakMap();
+function joinSharedRead(dataSource, resource, userId, want) {
+  let scopes = openReads.get(dataSource);
+  if (!scopes) {
+    scopes = /* @__PURE__ */ new Map();
+    openReads.set(dataSource, scopes);
+  }
+  const scope = JSON.stringify([resource, userId]);
+  const open = scopes.get(scope);
+  if (open) {
+    if ("key" in want) open.keys.add(want.key);
+    else open.prefixes.add(want.prefix);
+    return open;
+  }
+  const keys = new Set("key" in want ? [want.key] : []);
+  const prefixes = new Set("prefix" in want ? [want.prefix] : []);
+  const opened = scopes;
+  const read = {
+    keys,
+    prefixes,
+    answer: Promise.resolve().then(async () => {
+      if (opened.get(scope) === read) opened.delete(scope);
+      const query = preferenceQuery(userId, [...keys], [...prefixes]);
+      const result = await dataSource.find(resource, query);
+      const rows = result?.data ?? [];
+      return {
+        rows,
+        saturated: prefixes.size > 0 && rows.length >= (query.$top ?? Infinity)
+      };
+    })
+  };
+  scopes.set(scope, read);
+  return read;
+}
+function createPreferenceRowWriter(dataSource, resource, userId, key, onError) {
   let cachedRowId = null;
-  let saveChain = Promise.resolve();
   const findExisting = async () => {
-    const params = {
-      $filter: {
-        user_id: userId,
-        key
-      },
-      $top: 1
-    };
-    const result = await dataSource.find(resource, params);
-    const rows = result?.data ?? [];
-    const match = rows.find((r) => {
-      if (!r) return false;
-      const userMismatch = r.user_id !== void 0 && r.user_id !== userId;
-      const keyMismatch = r.key !== void 0 && r.key !== key;
-      return !userMismatch && !keyMismatch;
-    });
-    return match ?? null;
-  };
-  const decodeValue = (value) => {
-    if (Array.isArray(value)) return value;
-    if (typeof value === "string") {
-      try {
-        const parsed = JSON.parse(value);
-        return Array.isArray(parsed) ? parsed : [];
-      } catch {
-        return [];
-      }
-    }
-    return [];
+    const result = await dataSource.find(resource, preferenceQuery(userId, [key]));
+    return matchPreferenceRow(result?.data ?? [], userId, key);
   };
-  const upsert = async (items) => {
+  const upsert = async (value) => {
     if (cachedRowId !== null) {
       try {
-        await dataSource.update(resource, cachedRowId, { value: items });
+        await dataSource.update(resource, cachedRowId, { value });
         return;
       } catch (updateError) {
         cachedRowId = null;
@@ -1115,14 +2011,14 @@ function createObjectStackUserStateAdapter(options) {
     const existing = await findExisting();
     if (existing && existing.id !== void 0 && existing.id !== null) {
       cachedRowId = existing.id;
-      await dataSource.update(resource, existing.id, { value: items });
+      await dataSource.update(resource, existing.id, { value });
       return;
     }
     try {
       const created = await dataSource.create(resource, {
         user_id: userId,
         key,
-        value: items
+        value
       });
       const newId = created?.id;
       if (newId !== void 0 && newId !== null) cachedRowId = newId;
@@ -1130,21 +2026,74 @@ function createObjectStackUserStateAdapter(options) {
       const recovered = await findExisting();
       if (recovered && recovered.id !== void 0 && recovered.id !== null) {
         cachedRowId = recovered.id;
-        await dataSource.update(resource, recovered.id, { value: items });
+        await dataSource.update(resource, recovered.id, { value });
         return;
       }
       throw createError;
     }
   };
+  return {
+    remember(id) {
+      cachedRowId = id;
+    },
+    upsert,
+    find: findExisting
+  };
+}
+function matchPreferenceRow(rows, userId, key) {
+  const match = rows.find((r) => {
+    if (!r) return false;
+    const userMismatch = r.user_id !== void 0 && r.user_id !== userId;
+    const keyMismatch = r.key !== void 0 && r.key !== key;
+    return !userMismatch && !keyMismatch;
+  });
+  return match ?? null;
+}
+function createObjectStackUserStateAdapter(options) {
+  const {
+    dataSource,
+    userId,
+    key,
+    resource = DEFAULT_RESOURCE,
+    onError = () => {
+    }
+  } = options;
+  const writer = createPreferenceRowWriter(dataSource, resource, userId, key, onError);
+  let saveChain = Promise.resolve();
+  const loadExisting = async () => {
+    const read = joinSharedRead(dataSource, resource, userId, { key });
+    const { rows, saturated } = await read.answer;
+    if (read.keys.size === 1 && read.prefixes.size === 0) {
+      return matchPreferenceRow(rows, userId, key);
+    }
+    const own = rows.find(
+      (r) => r && r.key === key && (r.user_id === void 0 || r.user_id === userId)
+    );
+    if (own) return own;
+    if (saturated || rows.some((r) => r && r.key === void 0)) return writer.find();
+    return null;
+  };
+  const decodeValue = (value) => {
+    if (Array.isArray(value)) return value;
+    if (typeof value === "string") {
+      try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed) ? parsed : [];
+      } catch {
+        return [];
+      }
+    }
+    return [];
+  };
   return {
     async load() {
       try {
-        const row = await findExisting();
+        const row = await loadExisting();
         if (!row) {
-          cachedRowId = null;
+          writer.remember(null);
           return [];
         }
-        if (row.id !== void 0 && row.id !== null) cachedRowId = row.id;
+        if (row.id !== void 0 && row.id !== null) writer.remember(row.id);
         return decodeValue(row.value);
       } catch (error) {
         onError("load", error);
@@ -1152,7 +2101,7 @@ function createObjectStackUserStateAdapter(options) {
       }
     },
     async save(items) {
-      const run = saveChain.then(() => upsert(items)).catch((error) => {
+      const run = saveChain.then(() => writer.upsert(items)).catch((error) => {
         onError("save", error);
       });
       saveChain = run;
@@ -1160,6 +2109,137 @@ function createObjectStackUserStateAdapter(options) {
     }
   };
 }
+function createObjectStackUserPreferenceFamily(options) {
+  const {
+    dataSource,
+    userId,
+    prefix,
+    resource = DEFAULT_RESOURCE,
+    onError = () => {
+    }
+  } = options;
+  const writers = /* @__PURE__ */ new Map();
+  const chains = /* @__PURE__ */ new Map();
+  const writerFor = (key) => {
+    let writer = writers.get(key);
+    if (!writer) {
+      writer = createPreferenceRowWriter(dataSource, resource, userId, key, onError);
+      writers.set(key, writer);
+    }
+    return writer;
+  };
+  const decodeValue = (value) => {
+    let parsed = value;
+    if (typeof value === "string") {
+      try {
+        parsed = JSON.parse(value);
+      } catch {
+        return void 0;
+      }
+    }
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : void 0;
+  };
+  return {
+    prefix,
+    async load() {
+      try {
+        const read = joinSharedRead(dataSource, resource, userId, { prefix });
+        const { rows } = await read.answer;
+        const out = {};
+        for (const row of rows) {
+          if (!row || typeof row.key !== "string" || !row.key.startsWith(prefix)) continue;
+          if (row.user_id !== void 0 && row.user_id !== userId) continue;
+          if (row.id !== void 0 && row.id !== null) writerFor(row.key).remember(row.id);
+          const value = decodeValue(row.value);
+          if (value !== void 0) out[row.key] = value;
+        }
+        return out;
+      } catch (error) {
+        onError("load", error);
+        return {};
+      }
+    },
+    async save(key, value) {
+      if (!key.startsWith(prefix) || key.length === prefix.length) {
+        onError("save", new Error(`key "${key}" is not in the family "${prefix}"`));
+        return;
+      }
+      const run = (chains.get(key) ?? Promise.resolve()).then(() => writerFor(key).upsert(value)).catch((error) => {
+        onError("save", error);
+      });
+      chains.set(key, run);
+      return run;
+    }
+  };
+}
+
+// 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);
+}
+function readDraftChanges(resp) {
+  if (!resp || typeof resp !== "object") return null;
+  const changes = resp.draftChanges;
+  return Array.isArray(changes) ? changes : null;
+}
+function isPathPrefix(prefix, path) {
+  if (prefix.length > path.length) return false;
+  for (let i = 0; i < prefix.length; i++) if (prefix[i] !== path[i]) return false;
+  return true;
+}
+function governingDraftChange(changes, path) {
+  let best = null;
+  for (const change of changes ?? []) {
+    if (!isPathPrefix(change.path, path)) continue;
+    if (!best || change.path.length > best.path.length) best = change;
+  }
+  return best;
+}
+function draftChangesUnder(changes, path) {
+  return (changes ?? []).filter((change) => change.path.length > path.length && isPathPrefix(path, change.path));
+}
+
+// src/picklist-binding.ts
+function dropServedPicklistOptions(body) {
+  if (!body || typeof body !== "object") return body;
+  const fields = body.fields;
+  if (Array.isArray(fields)) {
+    let changed = false;
+    const next = fields.map((def) => {
+      const stripped = withoutServedOptions(def);
+      if (stripped !== def) changed = true;
+      return stripped;
+    });
+    return changed ? { ...body, fields: next } : body;
+  }
+  if (fields && typeof fields === "object") {
+    let changed = false;
+    const next = Object.fromEntries(
+      Object.entries(fields).map(([name, def]) => {
+        const stripped = withoutServedOptions(def);
+        if (stripped !== def) changed = true;
+        return [name, stripped];
+      })
+    );
+    return changed ? { ...body, fields: next } : body;
+  }
+  return body;
+}
+function withoutServedOptions(def) {
+  if (!def || typeof def !== "object" || Array.isArray(def)) return def;
+  const record = def;
+  if (record.picklist === void 0) return def;
+  if (!Object.prototype.hasOwnProperty.call(record, "options")) return def;
+  const { options: _served, ...authored } = record;
+  return authored;
+}
 
 // src/index.ts
 var FILTER_OPERATOR_ALIASES = {
@@ -1218,37 +2298,136 @@ var FILTER_OPERATOR_ALIASES = {
   before: "<",
   after: ">"
 };
-function normalizeFilterOperator2(op) {
-  if (typeof op !== "string") return null;
-  const lower = op.toLowerCase();
-  return FILTER_OPERATOR_ALIASES[lower] ?? FILTER_OPERATOR_ALIASES[op] ?? 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 = describeFilterEntry(entry);
+    super(
+      `Filter entry ${index} is not a usable filter rule (${shown}). Expected { field, operator, value } with a non-empty field.`
+    );
+    __publicField(this, "code", "INVALID_FILTER");
+    __publicField(this, "httpStatus", 400);
+    __publicField(this, "entry");
+    __publicField(this, "index");
+    this.name = "MalformedFilterError";
+    this.entry = entry;
+    this.index = index;
+  }
+};
+function isMalformedFilterError(error) {
+  if (!error || typeof error !== "object") return false;
+  const e = error;
+  return e.code === "INVALID_FILTER" || e.name === "MalformedFilterError";
+}
+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 MalformedFilterError = class extends Error {
-  constructor(entry, index) {
-    const shown = JSON.stringify(entry) ?? String(entry);
+var UnlowerableAnalyticsFilterError = class extends Error {
+  constructor(filter, resource, detail) {
+    const shown = JSON.stringify(filter) ?? String(filter);
     super(
-      `Filter entry ${index} is not a usable filter rule (${shown}). Expected { field, operator, value } with a non-empty field.`
+      `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);
-    __publicField(this, "entry");
-    __publicField(this, "index");
-    this.name = "MalformedFilterError";
-    this.entry = entry;
-    this.index = index;
+    /** 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 isMalformedFilterError(error) {
-  if (!error || typeof error !== "object") return false;
-  const e = error;
-  return e.code === "INVALID_FILTER" || e.name === "MalformedFilterError";
+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) {
+function objectFilterEntryToAST(entry, index) {
   if (!entry || typeof entry !== "object") return null;
   const field = entry.field;
   const rawOp = entry.operator ?? entry.op ?? "=";
-  const op = normalizeFilterOperator2(rawOp);
+  const op = toAstFilterOperator(rawOp);
   if (!field || !op) return null;
+  if (op === "icontains" && isRefusedTextComparand2(entry.value)) {
+    refuseTextComparandEntry(entry, index, String(field), rawOp);
+  }
   return [String(field), op, entry.value];
 }
 function isObjectFilterEntryForm(filter) {
@@ -1257,8 +2436,8 @@ function isObjectFilterEntryForm(filter) {
 }
 function objectFilterEntriesToAST(entries) {
   const nodes = entries.map((entry, i) => {
-    if (Array.isArray(entry)) return translateFilterChild(entry);
-    const tuple = objectFilterEntryToAST(entry);
+    if (Array.isArray(entry)) return translateFilterChild(entry, i);
+    const tuple = objectFilterEntryToAST(entry, i);
     if (!tuple) throw new MalformedFilterError(entry, i);
     return tuple;
   });
@@ -1269,15 +2448,17 @@ function translateFilterArray(filter) {
   if (isObjectFilterEntryForm(filter)) return objectFilterEntriesToAST(filter);
   const head = filter[0];
   if (typeof head === "string" && LOGICAL_AST_HEADS.has(head.toLowerCase())) {
-    return [head, ...filter.slice(1).map(translateFilterChild)];
+    return [head, ...filter.slice(1).map((child, i) => translateFilterChild(child, i + 1))];
+  }
+  if (filter.every((child) => Array.isArray(child))) {
+    return filter.map((child, i) => translateFilterChild(child, i));
   }
-  if (filter.every((child) => Array.isArray(child))) return filter.map(translateFilterChild);
   return filter;
 }
-function translateFilterChild(child) {
+function translateFilterChild(child, index) {
   if (Array.isArray(child)) return child.length > 0 ? translateFilterArray(child) : child;
   if (child && typeof child === "object" && child.field !== void 0) {
-    const tuple = objectFilterEntryToAST(child);
+    const tuple = objectFilterEntryToAST(child, index);
     if (tuple) return tuple;
   }
   return child;
@@ -1294,6 +2475,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") {
@@ -1311,6 +2516,7 @@ function serializeOrderBy(orderby) {
   }
   return void 0;
 }
+var VIEW_LIST_KEY = "list:view";
 var discoveryCache = /* @__PURE__ */ new Map();
 async function getSharedDiscovery(baseUrl, fetcher) {
   const key = baseUrl || "<default>";
@@ -1356,6 +2562,14 @@ 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 AnalyticsNotInstalledError = class extends Error {
   constructor(surface, detail, serverCode) {
     super(
@@ -1424,6 +2638,25 @@ var AnalyticsUnauthenticatedError = class extends Error {
     this.serverMessage = opts.serverMessage;
   }
 };
+var AnalyticsForbiddenError = class extends Error {
+  constructor(opts = {}) {
+    super(
+      `Analytics query refused: this user may not read the data behind ${opts.datasetName ? `dataset "${opts.datasetName}"` : "this dataset"}.` + (opts.serverMessage ? ` (server said: ${opts.serverMessage})` : "")
+    );
+    __publicField(this, "code", "PERMISSION_DENIED");
+    __publicField(this, "httpStatus", 403);
+    /** The server's own ADR-0112 code — the field this branch was chosen BY. */
+    __publicField(this, "serverCode");
+    /** The server's own message, verbatim (diagnostics only). */
+    __publicField(this, "serverMessage");
+    /** The dataset the refused query asked for, when it named one. */
+    __publicField(this, "datasetName");
+    this.name = "AnalyticsForbiddenError";
+    this.serverCode = opts.serverCode;
+    this.serverMessage = opts.serverMessage;
+    this.datasetName = opts.datasetName;
+  }
+};
 function readAnalyticsErrorEnvelope(body) {
   if (!body || typeof body !== "object") return {};
   const flat = body;
@@ -1446,6 +2679,30 @@ var AnalyticsQueryRejectedError = class extends Error {
     this.serverCode = serverCode;
   }
 };
+var AnalyticsResultShapeError = class extends Error {
+  constructor(resource, result) {
+    const value = result;
+    const envelope = Array.isArray(value?.data?.rows);
+    const received = result === null ? "null" : Array.isArray(result) ? "an array" : typeof result !== "object" ? typeof result : `an object with keys [${Object.keys(result).join(", ")}]`;
+    super(
+      envelope ? `aggregate('${resource}'): client.analytics.query resolved to the \`{ data: { rows } }\` envelope, not to an AnalyticsResult. @objectstack/client resolves this method to the payload itself since 17.3.0 (objectstack#13079), and this adapter reads \`rows\` only: an older client is installed beside it, or something between the client and POST /analytics/query wraps the payload a second time. Install @objectstack/client 17.3.0 or later.` : `aggregate('${resource}'): client.analytics.query resolved to ${received}, which has no \`rows\` array, so it is not an AnalyticsResult. This adapter reads \`rows\` only (objectui#7028).`
+    );
+    __publicField(this, "code", "ANALYTICS_RESULT_SHAPE_INVALID");
+    /** The object `aggregate()` was called for. */
+    __publicField(this, "resource");
+    /**
+     * True when the value is the envelope the client stopped handing back at
+     * 17.3.0 — `{ success, data: { rows } }`, or its `{ data: { rows } }` core.
+     */
+    __publicField(this, "envelope");
+    /** What the value was, so the producer is identifiable from a log. */
+    __publicField(this, "received");
+    this.name = "AnalyticsResultShapeError";
+    this.resource = resource;
+    this.envelope = envelope;
+    this.received = received;
+  }
+};
 function classifyAnalyticsFailure(error) {
   const err = error ?? {};
   const code = typeof err.code === "string" && err.code.length > 0 ? err.code : void 0;
@@ -1457,11 +2714,11 @@ function classifyAnalyticsFailure(error) {
   if (errorCodeIs({ code }, "VALIDATION_FAILED")) return { kind: "rejected", code, message };
   if (errorCodeIs({ code }, "UNAUTHENTICATED")) return { kind: "unauthenticated", code, message };
   if (errorCodeIs({ code }, "CUBE_NOT_FOUND")) return { kind: "cube-not-found", code, message };
+  if (status === 400) return { kind: "rejected", code, message };
   if (code === void 0) {
     if (status !== void 0 && ANALYTICS_ABSENT_STATUSES.includes(status)) {
       return { kind: "not-installed", code, message };
     }
-    if (status === 400) return { kind: "rejected", code, message };
     if (status === 401) return { kind: "unauthenticated", code, message };
   }
   return { kind: "unknown", code, message };
@@ -1473,9 +2730,22 @@ var ConcurrentUpdateError = class extends Error {
     __publicField(this, "httpStatus", 409);
     __publicField(this, "currentVersion");
     __publicField(this, "currentRecord");
+    /**
+     * The refusal text the PRODUCER marked as addressed to the end user
+     * (`ApiErrorSchema.userMessage`, objectstack `79c46da90`), or `null` when the
+     * refusal carried no marking.
+     *
+     * Declared on the class because this error has no `details` bag: the shared
+     * reader (`declaredUserMessage` in `@object-ui/react`) looks at the
+     * top-level field first, so parking it here is what makes the marking
+     * readable at the surface. The contract is status-agnostic — a 409 carries
+     * it exactly like a 400 or a 403 does.
+     */
+    __publicField(this, "userMessage");
     this.name = "ConcurrentUpdateError";
     this.currentVersion = opts.currentVersion;
     this.currentRecord = opts.currentRecord;
+    this.userMessage = opts.userMessage ?? null;
   }
 };
 function isConcurrentUpdateError(error) {
@@ -1483,10 +2753,18 @@ function isConcurrentUpdateError(error) {
   const e = error;
   return e.code === "CONCURRENT_UPDATE" || e.name === "ConcurrentUpdateError";
 }
+function liftUserMessage(e, details) {
+  if (typeof e.userMessage === "string" && e.userMessage.trim()) return e.userMessage;
+  if (typeof details.userMessage === "string" && details.userMessage.trim()) {
+    return details.userMessage;
+  }
+  return null;
+}
 function normaliseClientError(error) {
   if (!error || typeof error !== "object") return error;
   const e = error;
   const details = e.details ?? {};
+  const userMessage = liftUserMessage(e, details);
   if (e.code === "VALIDATION_FAILED" || e.name === "ValidationError") {
     const rawFields = Array.isArray(details.fields) ? details.fields : Array.isArray(e.fields) ? e.fields : [];
     const validationErrors = rawFields.map((f) => {
@@ -1500,15 +2778,21 @@ function normaliseClientError(error) {
       typeof e.message === "string" ? e.message : "Validation failed",
       validationErrors[0]?.field,
       validationErrors,
-      { fields: rawFields }
+      // The marking rides the details bag exactly the way `fields` already
+      // does, landing on `err.details.userMessage` — the second of the two
+      // places the shared reader looks. Purely additive: `field`,
+      // `validationErrors` and `fields` are untouched, so the per-field
+      // marking a form already draws keeps working. Omitted entirely when
+      // unmarked, so an unmarked refusal carries no empty key.
+      userMessage === null ? { fields: rawFields } : { fields: rawFields, userMessage }
     );
   }
-  if (e.code !== "CONCURRENT_UPDATE" && e.httpStatus !== 409) return error;
   if (e.code !== "CONCURRENT_UPDATE") return error;
   return new ConcurrentUpdateError({
     currentVersion: typeof details.currentVersion === "string" ? details.currentVersion : null,
     currentRecord: details.currentRecord ?? null,
-    message: typeof e.message === "string" ? e.message : void 0
+    message: typeof e.message === "string" ? e.message : void 0,
+    userMessage
   });
 }
 function formatHttpFailureMessage(message, meta) {
@@ -1563,6 +2847,80 @@ function createQuietHttpLogger() {
   };
   return logger;
 }
+var RECOGNIZED_DROP_REASONS = new Set(
+  DroppedFieldsEventSchema.shape.reason.options
+);
+var UNRECOGNIZED_DROP_REASON = "objectui:unrecognized-drop-reason";
+function isRecognizedDropReason(reason) {
+  return RECOGNIZED_DROP_REASONS.has(reason);
+}
+function isWireDroppedFieldsEntry(e) {
+  return !!e && typeof e === "object" && Array.isArray(e.fields) && e.fields.some((f) => typeof f === "string");
+}
+function asDroppedFieldsNotice(entry, fallbackObject) {
+  const fields = entry.fields.filter((f) => typeof f === "string");
+  const object = typeof entry.object === "string" ? entry.object : fallbackObject;
+  if (isRecognizedDropReason(entry.reason)) {
+    return { ...entry, object, fields, reason: entry.reason };
+  }
+  return {
+    ...entry,
+    object,
+    fields,
+    reason: UNRECOGNIZED_DROP_REASON,
+    unrecognizedReason: entry.reason
+  };
+}
+var UNATTRIBUTED_STRIP_OBJECT = "";
+var META_ROUTE_ABSENT_CODES = ["ROUTE_NOT_FOUND", "NOT_IMPLEMENTED"];
+var IMPORT_MAPPINGS_UNKNOWN_KIND_CODE = "INVALID_REQUEST";
+var IMPORT_MAPPINGS_UNKNOWN_KIND_STATUS = 400;
+var META_ABSENT_STATUSES = [404, 501];
+var META_REFUSAL_CODES = ["UNAUTHENTICATED", "PERMISSION_DENIED"];
+var META_REFUSAL_STATUSES = [401, 403, 405];
+function classifyImportMappingsFailure(error) {
+  const err = error ?? {};
+  const code = typeof err.code === "string" && err.code.length > 0 ? err.code : void 0;
+  const message = typeof err.message === "string" ? err.message : void 0;
+  const status = typeof err.httpStatus === "number" ? err.httpStatus : typeof err.status === "number" ? err.status : typeof err.statusCode === "number" ? err.statusCode : void 0;
+  const found = { code, status, message };
+  if (errorCodeIsAnyOf({ code }, META_ROUTE_ABSENT_CODES)) {
+    return { kind: "not-served", ...found };
+  }
+  if (errorCodeIs({ code }, IMPORT_MAPPINGS_UNKNOWN_KIND_CODE) && status === IMPORT_MAPPINGS_UNKNOWN_KIND_STATUS) {
+    return { kind: "not-served", ...found };
+  }
+  if (errorCodeIsAnyOf({ code }, META_REFUSAL_CODES)) {
+    return { kind: "refused", ...found };
+  }
+  if (status !== void 0 && META_REFUSAL_STATUSES.includes(status)) {
+    return { kind: "refused", ...found };
+  }
+  if (code === void 0 && status !== void 0 && META_ABSENT_STATUSES.includes(status)) {
+    return { kind: "not-served", ...found };
+  }
+  return { kind: "unreadable", ...found };
+}
+function classifyViewsFailure(error) {
+  const err = error ?? {};
+  const code = typeof err.code === "string" && err.code.length > 0 ? err.code : void 0;
+  const message = typeof err.message === "string" ? err.message : void 0;
+  const status = typeof err.httpStatus === "number" ? err.httpStatus : typeof err.status === "number" ? err.status : typeof err.statusCode === "number" ? err.statusCode : void 0;
+  const found = { code, status, message };
+  if (errorCodeIsAnyOf({ code }, META_ROUTE_ABSENT_CODES)) {
+    return { kind: "not-served", ...found };
+  }
+  if (errorCodeIsAnyOf({ code }, META_REFUSAL_CODES)) {
+    return { kind: "refused", ...found };
+  }
+  if (status !== void 0 && META_REFUSAL_STATUSES.includes(status)) {
+    return { kind: "refused", ...found };
+  }
+  if (code === void 0 && status !== void 0 && META_ABSENT_STATUSES.includes(status)) {
+    return { kind: "not-served", ...found };
+  }
+  return { kind: "unreadable", ...found };
+}
 function stableStringify(value) {
   if (value === null || typeof value !== "object") return JSON.stringify(value);
   if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
@@ -1577,6 +2935,16 @@ function sameWireValue(a, b) {
   if (aEmpty || bEmpty) return aEmpty && bEmpty;
   return stableStringify(a) === stableStringify(b);
 }
+function readWriteWarnings(result) {
+  const raw = result?.warnings;
+  if (!Array.isArray(raw) || raw.length === 0) return [];
+  const out = [];
+  for (const entry of raw) {
+    const parsed = ValidateDataIssueSchema.safeParse(entry);
+    if (parsed.success) out.push(parsed.data);
+  }
+  return out;
+}
 function withoutNoOpDrops(droppedFields, sent, stored) {
   if (!sent || !stored || typeof sent !== "object" || typeof stored !== "object") {
     return droppedFields;
@@ -1595,20 +2963,14 @@ function withoutNoOpDrops(droppedFields, sent, stored) {
   }
   return out;
 }
+var VIEW_ITEM_ROUND_TRIP_KEYS = Object.keys(VIEW_CONSOLE_ROUND_TRIP_KEYS).filter((key) => VIEW_CONSOLE_ROUND_TRIP_KEYS[key].includes("viewItem"));
 function viewItemObjectName(item) {
   const spec = item?.list ?? item;
-  return spec?.data?.object ?? spec?.object ?? spec?.objectName;
+  return spec?.data?.object ?? spec?.object;
 }
 var VIEW_OVERLAY_MARKER = "_isOverride";
-function isLegacyOverlayRow(item, spec) {
-  if (spec && spec.config && typeof spec.config === "object") return false;
-  const viewKind = item?.viewKind ?? spec?.viewKind;
-  return viewKind === "list";
-}
 function isPersonalizationOverlayRow(item, spec) {
-  if (item?.[VIEW_OVERLAY_MARKER] === true) return true;
-  if (spec?.[VIEW_OVERLAY_MARKER] === true) return true;
-  return isLegacyOverlayRow(item, spec);
+  return item?.[VIEW_OVERLAY_MARKER] === true || spec?.[VIEW_OVERLAY_MARKER] === true;
 }
 var VIEW_OVERLAY_OWNED_KEYS = Object.freeze([
   "rowHeight",
@@ -1640,8 +3002,9 @@ function narrowPersonalizationOverlay(row) {
 function unwrapViewDraft(resp) {
   if (!resp || typeof resp !== "object") return null;
   const env = resp;
-  const body = "item" in env ? env.item : env;
-  if (!body || typeof body !== "object") return null;
+  const raw = "item" in env ? env.item : env;
+  if (!raw || typeof raw !== "object") return null;
+  const body = stripReadDecorations2(raw);
   const spec = body.list ?? body;
   if (!spec || typeof spec !== "object") return null;
   return Object.keys(spec).length > 0 ? spec : null;
@@ -1662,6 +3025,10 @@ function mergeViewPatch(current, partial, viewName, objectName) {
     object: current?.object || current?.data?.object || objectName
   };
 }
+function isCallerAbort(error, init) {
+  if (init?.signal?.aborted) return true;
+  return error?.name === "AbortError";
+}
 var ObjectStackAdapter = class {
   constructor(config) {
     __publicField(this, "client");
@@ -1685,6 +3052,13 @@ var ObjectStackAdapter = class {
     // multiple sibling components requesting the same dataset on first paint)
     // into a single network round trip.
     __publicField(this, "inflightFinds", /* @__PURE__ */ new Map());
+    // In-flight findOne() reads keyed by resource + record id + serialized
+    // params, shared the same way (objectui#11699). Opening one record page
+    // asked for the same record twice at once: `record:details`' DetailView
+    // re-runs its load effect while its first read is still on the wire. A
+    // write to a resource drops that resource's entries (see `emitMutation`),
+    // so a read asked after a save is never answered by one sent before it.
+    __publicField(this, "inflightFindOnes", /* @__PURE__ */ new Map());
     // Resources that have responded 404 at least once (collection not installed
     // on this backend). Subsequent find() calls short-circuit to an empty result
     // so optional collections like sys_presence don't hammer the server with
@@ -1697,10 +3071,10 @@ var ObjectStackAdapter = class {
     // one adapter that has to cope with a backend lacking server atomicity (#2679).
     __publicField(this, "batchUnsupported", false);
     // The server's declared cross-object atomic-batch capability, read from
-    // discovery at connect() (framework #3298 / objectui #2693). `true` → the
+    // discovery at connect() (objectstack-ai/objectstack#3298 / objectui #2693). `true` → the
     // backend GUARANTEES an atomic `/batch`, so batchTransaction trusts it and
     // never degrades to the non-atomic emulation (any failure surfaces as a real
-    // error). `false` or `undefined` (capability absent → backend predates #3298)
+    // error). `false` or `undefined` (capability absent → backend predates objectstack-ai/objectstack#3298)
     // → keep the legacy runtime-probe + emulation fallback so a save is still
     // possible; dropping it there would turn "saves, less safe" into "no save
     // path" on older backends (#2679 compatibility constraint).
@@ -1711,7 +3085,7 @@ var ObjectStackAdapter = class {
     // inline-edit "Save All" writes without a manual reload.
     __publicField(this, "mutationListeners", /* @__PURE__ */ new Set());
     // Subscribers registered via onWriteWarning(). Emitted after a create/update
-    // whose response carried `droppedFields` (framework #3431/#3455) so the app
+    // whose response carried `droppedFields` (objectstack-ai/objectstack#3431 / objectstack-ai/objectstack#3455) so the app
     // shell can surface a toast instead of the strip passing silently.
     __publicField(this, "writeWarningListeners", /* @__PURE__ */ new Set());
     // Subscribers registered via onSaveAdvisory(). Emitted after a metadata save
@@ -1720,62 +3094,85 @@ 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());
-    this.client = new ObjectStackClient({ ...config, logger: createQuietHttpLogger() });
+    // 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());
+    const transport = config.fetch || globalThis.fetch.bind(globalThis);
+    this.fetchImpl = (input, init) => this.observeServerAnswer(() => transport(input, init), init);
+    this.client = new ObjectStackClient({
+      ...config,
+      fetch: this.fetchImpl,
+      logger: createQuietHttpLogger()
+    });
     this.installSaveAdvisoryInterceptor();
     this.metadataCache = new MetadataCache(config.cache);
+    this.installViewListShare();
     this.autoReconnect = config.autoReconnect ?? true;
     this.maxReconnectAttempts = config.maxReconnectAttempts ?? 3;
     this.reconnectDelay = config.reconnectDelay ?? 1e3;
     this.baseUrl = config.baseUrl;
     this.token = config.token;
-    this.fetchImpl = config.fetch || globalThis.fetch.bind(globalThis);
   }
   /**
    * Ensure the client is connected to the server.
    * Call this before making requests or it will auto-connect on first request.
+   *
+   * With `autoReconnect`, a failed discovery read is retried up to
+   * `maxReconnectAttempts` times with exponential backoff. The promise resolves
+   * once discovery answers and rejects with the last `ConnectionError` once the
+   * retries are spent (objectui#12318).
    */
   async connect() {
     if (this.connected) return;
     if (this.connectPromise) return this.connectPromise;
     this.setConnectionState("connecting");
-    this.connectPromise = (async () => {
-      try {
-        const baseUrl = this.baseUrl || "";
-        const discoveryUrl = baseUrl ? `${baseUrl.replace(/\/$/, "")}/api/v1/discovery` : "/api/v1/discovery";
-        const data = await getSharedDiscovery(baseUrl, async () => {
-          const res = await this.fetchImpl(discoveryUrl, {
-            method: "GET",
-            headers: this.token ? { Authorization: `Bearer ${this.token}` } : void 0
-          });
-          if (!res.ok) {
-            throw new Error(`discovery ${res.status} ${res.statusText}`);
-          }
-          const body = await res.json();
-          return body && typeof body.success === "boolean" && "data" in body ? body.data : body;
+    this.connectPromise = this.attemptConnect().finally(() => {
+      this.connectPromise = null;
+    });
+    return this.connectPromise;
+  }
+  /**
+   * One discovery attempt, and the retry that follows it when it fails with
+   * budget left. Runs inside the promise {@link connect} hands every caller.
+   */
+  async attemptConnect() {
+    try {
+      const baseUrl = this.baseUrl || "";
+      const discoveryUrl = baseUrl ? `${baseUrl.replace(/\/$/, "")}/api/v1/discovery` : "/api/v1/discovery";
+      const data = await getSharedDiscovery(baseUrl, async () => {
+        const res = await this.fetchImpl(discoveryUrl, {
+          method: "GET",
+          headers: this.token ? { Authorization: `Bearer ${this.token}` } : void 0
         });
-        this.client.discoveryInfo = data;
-        this.atomicBatchCapability = readTransactionalBatchCapability(data);
-        this.connected = true;
-        this.reconnectAttempts = 0;
-        this.setConnectionState("connected");
-      } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : "Failed to connect to ObjectStack server";
-        const connectionError = new ConnectionError(
-          errorMessage,
-          void 0,
-          { originalError: error }
-        );
-        this.setConnectionState("error", connectionError);
-        if (this.autoReconnect && this.reconnectAttempts < this.maxReconnectAttempts) {
-          await this.attemptReconnect();
-        } else {
-          throw connectionError;
+        if (!res.ok) {
+          throw new Error(`discovery ${res.status} ${res.statusText}`);
         }
-      } finally {
-        this.connectPromise = null;
+        const body = await res.json();
+        return body && typeof body.success === "boolean" && "data" in body ? body.data : body;
+      });
+      this.client.discoveryInfo = data;
+      this.atomicBatchCapability = readTransactionalBatchCapability(data);
+      this.connected = true;
+      this.reconnectAttempts = 0;
+      this.setConnectionState("connected");
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Failed to connect to ObjectStack server";
+      const connectionError = new ConnectionError(
+        errorMessage,
+        void 0,
+        { originalError: error }
+      );
+      this.setConnectionState("error", connectionError);
+      if (this.autoReconnect && this.reconnectAttempts < this.maxReconnectAttempts) {
+        await this.attemptReconnect();
+      } else {
+        throw connectionError;
       }
-    })();
-    return this.connectPromise;
+    }
   }
   /**
    * Attempt to reconnect to the server with exponential backoff
@@ -1785,8 +3182,7 @@ var ObjectStackAdapter = class {
     this.setConnectionState("reconnecting");
     const delay = this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1);
     await new Promise((resolve) => setTimeout(resolve, delay));
-    this.connected = false;
-    await this.connect();
+    await this.attemptConnect();
   }
   /**
    * Get the current connection state
@@ -1842,6 +3238,63 @@ var ObjectStackAdapter = class {
       }
     });
   }
+  /**
+   * Run one request through the adapter's fetch and let its outcome move the
+   * connection state (objectui#12295). Before the first successful
+   * {@link connect} this records nothing: `connect()` owns the state until
+   * then, and its own discovery read passes through here too.
+   *
+   * - **Answered** — the fetch resolved with a Response, whatever its status.
+   *   A 4xx or 5xx is an answer: the server is reachable, so it counts the
+   *   same as a 200 and ends any outage.
+   * - **Not answered** — the fetch rejected: no HTTP answer at all (refused,
+   *   reset, DNS, an offline browser). A rejection the caller asked for by
+   *   aborting is not evidence about the server and records nothing.
+   *
+   * The rejection or the Response reaches the caller unchanged.
+   */
+  async observeServerAnswer(send, init) {
+    let response;
+    try {
+      response = await send();
+    } catch (error) {
+      if (!isCallerAbort(error, init)) this.noteServerUnanswered(error);
+      throw error;
+    }
+    this.noteServerAnswered();
+    return response;
+  }
+  /** An answered request after the first connect: the server is reachable. */
+  noteServerAnswered() {
+    if (!this.connected) return;
+    this.reconnectAttempts = 0;
+    if (this.connectionState !== "connected") this.setConnectionState("connected");
+  }
+  /**
+   * An unanswered request after the first connect. It spends the adapter's own
+   * retry window — the `autoReconnect` / `maxReconnectAttempts` budget that
+   * {@link connect} grants a failed discovery — counted in the requests the
+   * host already makes rather than in timed probes: while the budget lasts the
+   * state is `reconnecting`, and the first unanswered request past it moves the
+   * state to `error`. No timer and no request of the adapter's own is involved;
+   * the next answered request, whenever it comes, restores `connected`.
+   */
+  noteServerUnanswered(error) {
+    if (!this.connected || this.connectionState === "error") return;
+    if (this.autoReconnect && this.reconnectAttempts < this.maxReconnectAttempts) {
+      this.reconnectAttempts++;
+      if (this.connectionState !== "reconnecting") this.setConnectionState("reconnecting");
+      return;
+    }
+    this.setConnectionState(
+      "error",
+      new ConnectionError(
+        error instanceof Error ? error.message : "ObjectStack server did not answer",
+        void 0,
+        { originalError: error }
+      )
+    );
+  }
   /**
    * Emit batch progress event to listeners
    */
@@ -1863,9 +3316,7 @@ var ObjectStackAdapter = class {
       return { data: [], total: 0 };
     }
     const key = `${resource}::${stableStringify(params)}`;
-    const existing = this.inflightFinds.get(key);
-    if (existing) return existing;
-    const promise = (async () => {
+    return this.shareInFlight(this.inflightFinds, key, async () => {
       await this.connect();
       if (params?.$expand && params.$expand.length > 0 || params?.$search != null && String(params.$search).trim() !== "") {
         const result = await this.rawFindWithPopulate(resource, params);
@@ -1882,11 +3333,25 @@ var ObjectStackAdapter = class {
         }
         throw err;
       }
-    })();
-    this.inflightFinds.set(key, promise);
+    });
+  }
+  /**
+   * Share one in-flight read among concurrent callers asking the same
+   * question: the first call for `key` issues `read()`, every call that
+   * arrives while it is still pending gets that same promise, and the entry is
+   * dropped the moment it settles — so nothing is cached past the round trip,
+   * a rejection reaches every caller that shared it and is not remembered, and
+   * the next call after settle issues a fresh read. Used by `find` and
+   * `findOne` (objectui#11699).
+   */
+  shareInFlight(inflight, key, read) {
+    const existing = inflight.get(key);
+    if (existing) return existing;
+    const promise = read();
+    inflight.set(key, promise);
     const cleanup = () => {
-      if (this.inflightFinds.get(key) === promise) {
-        this.inflightFinds.delete(key);
+      if (inflight.get(key) === promise) {
+        inflight.delete(key);
       }
     };
     promise.then(cleanup, cleanup);
@@ -1901,7 +3366,7 @@ var ObjectStackAdapter = class {
    * — a per-object metadata-driven search (ADR-0061) — this consults the search
    * index and ranks hits across objects, so it surfaces records the per-object
    * fanout misses. Global affordances (⌘K command palette, search page) prefer
-   * this path (framework #3371).
+   * this path (objectstack-ai/objectstack#3371).
    *
    * Returns `{ query, hits }`. A backend without the search plugin installed
    * answers `404`; we treat that as "no global search here" and return an empty
@@ -1934,10 +3399,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();
@@ -1965,8 +3430,16 @@ var ObjectStackAdapter = class {
   }
   /**
    * Find a single record by ID.
+   *
+   * Concurrent calls for the same resource, id and params share one request,
+   * exactly as `find` does (objectui#11699); see {@link shareInFlight}.
    */
   async findOne(resource, id, params) {
+    const key = `${resource}::${JSON.stringify(String(id))}::${stableStringify(params)}`;
+    return this.shareInFlight(this.inflightFindOnes, key, () => this.readOne(resource, id, params));
+  }
+  /** The one round trip behind {@link findOne}, unshared. */
+  async readOne(resource, id, params) {
     await this.connect();
     if (params?.$expand && params.$expand.length > 0) {
       try {
@@ -2006,6 +3479,10 @@ var ObjectStackAdapter = class {
    * mutation or starve the other subscribers, so each is isolated.
    */
   emitMutation(event) {
+    const prefix = `${event.resource}::`;
+    for (const key of Array.from(this.inflightFindOnes.keys())) {
+      if (key.startsWith(prefix)) this.inflightFindOnes.delete(key);
+    }
     for (const listener of this.mutationListeners) {
       try {
         listener(event);
@@ -2040,24 +3517,41 @@ 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`).
+   *
+   * The same answer's `warnings` (objectui#12107) rides this one event: it is
+   * emitted when either list is non-empty, so a write whose only news is an
+   * advisory rule hit still reaches the subscriber, with `droppedFields: []`.
    */
   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 stored = result?.record;
-    const droppedFields = withoutNoOpDrops(valid, sent, stored);
-    if (droppedFields.length === 0) return;
-    this.emitWriteWarning({ operation, resource, ...id !== void 0 ? { id } : {}, droppedFields });
+    let droppedFields = [];
+    if (Array.isArray(dropped) && dropped.length > 0) {
+      const valid = dropped.filter(isWireDroppedFieldsEntry).map((e) => asDroppedFieldsNotice(e, resource));
+      const stored = result?.record;
+      droppedFields = withoutNoOpDrops(valid, sent, stored);
+    }
+    const warnings = readWriteWarnings(result);
+    if (droppedFields.length === 0 && warnings.length === 0) return;
+    this.emitWriteWarning({
+      operation,
+      resource,
+      ...id !== void 0 ? { id } : {},
+      droppedFields,
+      ...warnings.length > 0 ? { warnings } : {}
+    });
   }
   /**
-   * Same, for the cross-object transactional batch (framework #3794). Its
+   * Same, for the cross-object transactional batch (objectstack-ai/objectstack#3794). Its
    * response hangs the events off a top-level `droppedFields` list, each tagged
    * with the `index` of the operation it came from — `results` entries are bare
    * record echoes with nowhere to hang a per-row list.
@@ -2073,13 +3567,13 @@ var ObjectStackAdapter = class {
     if (!Array.isArray(dropped) || dropped.length === 0) return;
     const results = payload?.results;
     for (const entry of dropped) {
-      if (!entry || typeof entry !== "object") continue;
+      if (!isWireDroppedFieldsEntry(entry)) continue;
       const e = entry;
-      if (!Array.isArray(e.fields) || e.fields.length === 0) continue;
       const op = typeof e.index === "number" ? operations[e.index] : void 0;
+      const object = typeof e.object === "string" ? e.object : typeof op?.object === "string" ? op.object : UNATTRIBUTED_STRIP_OBJECT;
       const stored = typeof e.index === "number" && Array.isArray(results) ? results[e.index] : void 0;
       const [live] = withoutNoOpDrops(
-        [{ object: e.object, fields: e.fields, reason: e.reason }],
+        [asDroppedFieldsNotice({ fields: e.fields, reason: e.reason }, object)],
         op?.data,
         stored
       );
@@ -2087,7 +3581,7 @@ var ObjectStackAdapter = class {
       const operation = (op?.action ?? "create") === "create" ? "create" : "update";
       this.emitWriteWarning({
         operation,
-        resource: e.object ?? op?.object ?? "",
+        resource: object,
         ...op?.id !== void 0 && op?.id !== null ? { id: op.id } : {},
         droppedFields: [live]
       });
@@ -2095,7 +3589,7 @@ var ObjectStackAdapter = class {
   }
   /**
    * Subscribe to write-warning events (a create/update dropped caller-supplied
-   * fields — #3431/#3455). Returns an unsubscribe function. The app shell uses
+   * fields — objectstack-ai/objectstack#3431 / objectstack-ai/objectstack#3455). Returns an unsubscribe function. The app shell uses
    * this to toast the user; the write itself already succeeded.
    */
   onWriteWarning(callback) {
@@ -2109,7 +3603,7 @@ var ObjectStackAdapter = class {
    * advisory findings on a save that SUCCEEDED (#4237; backend
    * objectstack#7435). Returns an unsubscribe function.
    *
-   * Deliberately the same seam as {@link onWriteWarning} (#3431/#3455), which
+   * Deliberately the same seam as {@link onWriteWarning} (objectstack-ai/objectstack#3431 / objectstack-ai/objectstack#3455), which
    * is what {@link MetadataSaveAdvisoryEvent}'s own declaration already said it
    * was modelled on. It is a SIBLING of that channel rather than a second
    * payload pushed down it: `WriteWarningEvent` is a closed shape whose
@@ -2146,6 +3640,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).
    *
@@ -2153,8 +3686,8 @@ var ObjectStackAdapter = class {
    *
    * `ObjectStackClient.meta.saveItem` is the second client class that writes
    * through `PUT /api/v1/meta/:type/:name`, and every one of its callers reaches
-   * it through an adapter this class constructed — the four inside this file
-   * (`updateViewConfig`, the two view paths, `updateDashboard`) via
+   * it through an adapter this class constructed — the three inside this file
+   * (the two view paths, `updateDashboard`) via
    * `this.client`, and every caller outside it via {@link getClient}, which
    * hands back this same instance: `MetadataService` (app-shell, five saves),
    * `useNavigationSync`, and plugin-designer's Create/EditAppPage. Wrapping the
@@ -2183,26 +3716,42 @@ var ObjectStackAdapter = class {
    *
    * Drafts are NEVER gated: the framework returns at its D1 early-return
    * (`if (args.state !== 'active') return null`) before running a rule, so a
-   * draft save produces no findings to withhold. This client class has no draft
-   * door at all to worry about — the SDK's `saveItem(type, name, item)` takes no
-   * mode and always writes the active door, which is exactly why the gate DOES
-   * run for its callers. `mode` on the emitted event is therefore derived from
-   * the response's own `state` rather than from a request-side flag that does
-   * not exist here: `'draft'` when the server says the row landed as a draft,
-   * `'publish'` otherwise. That keeps the event truthful about which door it
-   * came through instead of hard-coding one.
+   * draft save produces no findings to withhold. `mode` on the emitted event is
+   * derived from the response's own `state`, not from the caller's options:
+   * `'draft'` when the server says the row landed as a draft, `'publish'`
+   * otherwise. The server's answer is the one that says which door the write
+   * took, so the event cannot claim a door the request only asked for.
+   *
+   * ## Every argument is forwarded (objectui#12300)
+   *
+   * The SDK's `saveItem(type, name, item, options?)` carries the write's scope
+   * in its fourth argument, `SaveMetaItemOptions`: `packageId` (`?package=`),
+   * `force`, `mode` and `ifMatch`. This wrapper used to name three parameters
+   * and call the original with three, so that bag was dropped before the SDK
+   * saw it. Every caller reaching the SDK through {@link getClient} got a bare
+   * `PUT` whatever it passed, while the declared signature still accepted the
+   * bag, so nothing at the call site could tell. The wrapper now takes and
+   * passes the original's own parameter list, so it forwards whatever the SDK
+   * declares, today's bag and any later member, without naming one.
    */
   installSaveAdvisoryInterceptor() {
     const meta = this.client.meta;
     const original = meta.saveItem.bind(meta);
-    meta.saveItem = async (type, name, item) => {
-      const result = await original(type, name, item);
+    meta.saveItem = async (...args) => {
+      const [type, name] = args;
+      const result = await original(...args);
       try {
         const advisories = readSaveAdvisories(result);
         if (advisories.length > 0) {
           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
           });
@@ -2213,6 +3762,61 @@ var ObjectStackAdapter = class {
       return result;
     };
   }
+  /**
+   * Route this adapter's client's published view-list read through the one
+   * {@link VIEW_LIST_KEY} (objectui#13044).
+   *
+   * The app-shell `MetadataProvider` reads `client.meta.getItems('view')`
+   * through {@link getClient}; {@link listViews} and {@link listViewOverrides}
+   * read the same `GET /api/v1/meta/view`. Each used to put its own request on
+   * the wire, so one list-page open asked the server three times for one URL.
+   *
+   * A caller of the client keeps its contract, "ask the server": it is never
+   * answered from a settled entry. It joins a request already in flight for
+   * the same URL instead of sending a second one, and its answer is stored
+   * under {@link VIEW_LIST_KEY} (see {@link MetadataCache.share}), which is
+   * what {@link readViewList} answers this adapter's own readers from
+   * (objectui#13057). Only the bare call is routed: any argument after the
+   * type changes the URL, so such a call goes straight to the SDK.
+   *
+   * Every caller gets its own copy of the answer. Before this, every reader
+   * got its own parsed response, so a reader that changed what it was handed
+   * changed nothing anyone else read; a shared answer must not change that.
+   *
+   * Same wrap shape and the same bound as `installSaveAdvisoryInterceptor`:
+   * `meta` is an own property of a client this adapter built and never shares.
+   */
+  installViewListShare() {
+    const meta = this.client.meta;
+    const original = meta.getItems.bind(meta);
+    meta.getItems = ((...args) => {
+      if (args[0] !== "view" || args.length > 1) return original(...args);
+      return this.metadataCache.share(VIEW_LIST_KEY, () => original(...args)).then((answer) => structuredClone(answer));
+    });
+    for (const door of ["saveItem", "deleteItem", "publishItem", "rollbackItem"]) {
+      const write = meta[door];
+      if (typeof write !== "function") continue;
+      const bound = write.bind(meta);
+      meta[door] = (...args) => {
+        if (args[0] !== "view") return bound(...args);
+        return bound(...args).finally(() => this.metadataCache.invalidate?.(VIEW_LIST_KEY));
+      };
+    }
+  }
+  /**
+   * The published view list for this adapter's own readers
+   * ({@link listViews}, {@link listViewOverrides}): the answer stored under
+   * {@link VIEW_LIST_KEY} while it holds one (objectui#13057), else the
+   * client's read, which joins the request in flight for that key or starts
+   * one, and stores its answer (objectui#13044). Always a copy the caller may
+   * keep. Every path that should see a fresh list drops the key first; the
+   * list is in {@link VIEW_LIST_KEY}'s doc.
+   */
+  readViewList() {
+    const settled = this.metadataCache.getCachedSync(VIEW_LIST_KEY);
+    if (settled !== void 0) return Promise.resolve(structuredClone(settled));
+    return this.client.meta.getItems("view");
+  }
   async create(resource, data) {
     await this.connect();
     try {
@@ -2250,7 +3854,7 @@ var ObjectStackAdapter = class {
         data,
         opts?.ifMatch ? { ifMatch: opts.ifMatch } : void 0
       );
-      this.emitMutation({ type: "update", resource, id, record: { ...result.record } });
+      this.emitMutation({ type: "update", resource, id: String(id), record: { ...result.record } });
       this.notifyDroppedFields("update", resource, result, id, data);
       return result.record;
     } catch (err) {
@@ -2273,7 +3877,7 @@ var ObjectStackAdapter = class {
         opts?.ifMatch ? { ifMatch: opts.ifMatch } : void 0
       );
       if (result.success) {
-        this.emitMutation({ type: "delete", resource, id });
+        this.emitMutation({ type: "delete", resource, id: String(id) });
       }
       return result.success;
     } catch (err) {
@@ -2374,25 +3978,25 @@ var ObjectStackAdapter = class {
    * @returns Promise resolving to array of results
    */
   /**
-   * Cross-object transactional batch (ObjectStack #1604 / ADR-0034 item 4).
+   * Cross-object transactional batch (objectstack-ai/objectstack#1604 / ADR-0034 item 4).
    * Runs the operations in ONE server transaction — commit all or roll back
    * all. A field value of `{ $ref: <earlier op index> }` resolves to that op's
    * created id, so a child can reference its parent created earlier in the same
    * batch (master-detail).
    *
    * Transport: the published `@objectstack/client` SDK method
-   * `data.batchTransaction` (framework #3271; shipped since client v16, our
+   * `data.batchTransaction` (objectstack-ai/objectstack#3271; shipped since client v16, our
    * dependency floor). Per AGENTS.md §7 data always flows through the client —
    * never a hand-rolled `fetch('/api/v1/batch')`.
    *
-   * Fallback decision — declarative capability negotiation (framework #3298 /
+   * Fallback decision — declarative capability negotiation (objectstack-ai/objectstack#3298 /
    * objectui #2693). At connect() we read `capabilities.transactionalBatch`
    * from discovery:
    *   - Declared `true` → the backend GUARANTEES atomicity (declared ===
    *     enforced). We TRUST it: any batch failure — including 404/405/501 —
    *     surfaces as a real error. No non-atomic client-side compensation. This
    *     is the path modern backends take.
-   *   - Declared `false`, or ABSENT (backend predates #3298) → we can't rely on
+   *   - Declared `false`, or ABSENT (backend predates objectstack-ai/objectstack#3298) → we can't rely on
    *     server atomicity, so we keep the legacy behaviour: on 404/405 (no
    *     endpoint) or 501 (runtime without transactions) degrade to the
    *     client-side, NON-atomic {@link emulateBatchTransaction} so a save is
@@ -2816,9 +4420,10 @@ var ObjectStackAdapter = class {
     const res = await this.fetchImpl(url, { method: "GET", headers });
     if (!res.ok) {
       const errorBody = await res.json().catch(() => ({ message: res.statusText }));
-      const err = new Error(errorBody?.error?.message || errorBody?.message || res.statusText);
+      const envelope = readErrorEnvelope(errorBody);
+      const err = new Error(envelope.message ?? res.statusText);
       err.status = res.status;
-      err.code = errorBody?.code ?? errorBody?.error?.code;
+      err.code = envelope.code;
       err.httpStatus = res.status;
       throw err;
     }
@@ -2868,16 +4473,51 @@ var ObjectStackAdapter = class {
         queryParams.set("searchFields", request.searchFields.join(","));
       }
     }
+    return this.fetchExportBlob(resource, queryParams);
+  }
+  /**
+   * Download the server's import template:
+   * `GET /api/v1/data/:object/export?template=true` (objectui#9600).
+   *
+   * Same route as {@link exportDownload}, with the server's template switch. It
+   * sends only `template=true`: the server refuses the export's row parameters
+   * on a template request, and its answer is always an xlsx workbook.
+   *
+   * The server writes the template's labels in the request's locale, and the
+   * import accepts a translated label only in its own request's locale. The
+   * import request goes through `@objectstack/client`, which stamps
+   * `Accept-Language` with the client's locale when one is set (and the host's
+   * `fetch` stamps its own otherwise). This request bypasses the client, so it
+   * stamps the client's locale the same way. Both requests then carry the same
+   * locale.
+   */
+  async downloadImportTemplate(resource) {
+    const locale = this.client.getLocale();
+    return this.fetchExportBlob(
+      resource,
+      new URLSearchParams({ template: "true" }),
+      locale ? { "Accept-Language": locale } : void 0
+    );
+  }
+  /**
+   * GET `/api/v1/data/:object/export` with the given query and answer the body
+   * as a Blob. A failure throws an `Error` that carries the server's `status`
+   * and its ADR-0112 `code`. The one request path {@link exportDownload} and
+   * {@link downloadImportTemplate} share.
+   */
+  async fetchExportBlob(resource, queryParams, extraHeaders) {
     const baseUrl = this.baseUrl.replace(/\/$/, "");
     const hasApiVersionSuffix = /\/api\/v\d+$/i.test(baseUrl);
     const dataPath = hasApiVersionSuffix ? "/data" : "/api/v1/data";
     const url = `${baseUrl}${dataPath}/${encodeURIComponent(resource)}/export?${queryParams.toString()}`;
-    const headers = { ...this.getAuthHeaders() };
+    const headers = { ...this.getAuthHeaders(), ...extraHeaders };
     const res = await this.fetchImpl(url, { method: "GET", headers, credentials: "include" });
     if (!res.ok) {
       const errorBody = await res.json().catch(() => ({ message: res.statusText }));
-      const err = new Error(errorBody?.error?.message || errorBody?.message || res.statusText);
+      const envelope = readErrorEnvelope(errorBody);
+      const err = new Error(envelope.message ?? res.statusText);
       err.status = res.status;
+      err.code = envelope.code;
       throw err;
     }
     return await res.blob();
@@ -2898,7 +4538,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;
         }
       }
     }
@@ -2933,7 +4574,6 @@ var ObjectStackAdapter = class {
         () => this.fetchObjectSchemaFresh(objectName)
       );
       normalizeSchemaReferenceKeys(schema);
-      this.applyFieldWidgetOverrides(objectName, schema);
       return schema;
     } catch (error) {
       const errorObj = error;
@@ -2946,44 +4586,6 @@ var ObjectStackAdapter = class {
       throw createErrorFromResponse(errorObj, `getObjectSchema(${objectName})`);
     }
   }
-  /**
-   * ADR-0056 P2 (epic #2398) — stamp structured-widget hints onto platform
-   * fields whose framework type is a storage primitive (e.g. `textarea`) but
-   * whose authoring UX should be a structured editor. Only the render `widget`
-   * is added; the field's `type` (the storage contract) is untouched. Applied
-   * idempotently to the cached schema so form + detail both honor it. Widget
-   * components are registered as `field:<widget>` in `@object-ui/fields`.
-   */
-  applyFieldWidgetOverrides(objectName, schema) {
-    const OVERRIDES = {
-      // ADR-0056 pure model — a permission set's six authorization facets are
-      // *designed* in Studio's structured editors and only *assigned* (to
-      // users) in Setup. In Setup they render read-only as a summary + a
-      // "Design in Studio →" deep-link (the `permission-facet-link` widget),
-      // never as raw [Object]/JSON. The capability *editor* itself lives in
-      // Studio (epic #2398 P2).
-      sys_permission_set: {
-        object_permissions: "permission-facet-link",
-        field_permissions: "permission-facet-link",
-        system_permissions: "permission-facet-link",
-        row_level_security: "permission-facet-link",
-        tab_permissions: "permission-facet-link",
-        admin_scope: "permission-facet-link"
-      }
-    };
-    const overrides = OVERRIDES[objectName];
-    const fields = schema && typeof schema === "object" ? schema.fields : null;
-    if (!overrides || !fields) return;
-    for (const [fname, widget] of Object.entries(overrides)) {
-      if (Array.isArray(fields)) {
-        const f = fields.find((x) => x?.name === fname);
-        if (f && !f.widget) f.widget = widget;
-      } else {
-        const f = fields[fname];
-        if (f && !f.widget) f.widget = widget;
-      }
-    }
-  }
   /**
    * Fetch a single object's schema while always revalidating the browser cache.
    *
@@ -3018,13 +4620,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
@@ -3055,6 +4660,38 @@ var ObjectStackAdapter = class {
       return [];
     }
   }
+  /**
+   * List the items one metadata registry type declares —
+   * `GET /api/v1/meta/:type`, through the client's `meta.getItems` — as
+   * `{ name, label }` headers for the `position-ref` / `permission-ref` field
+   * widgets (objectui#7611).
+   *
+   * Unlike {@link getObjects}, a failure REJECTS (the `DataSource` contract):
+   * the transport's own error propagates, and an answer without the spec's
+   * `items` list is refused rather than read as an empty registry, so a
+   * failed load can never reach the widget as "this registry declares
+   * nothing". Uncached, like `getObjects`: an item authored in Studio is
+   * listed on the next form that opens.
+   *
+   * An item without a string `name` is not listed (the widget stores the
+   * name, so there is nothing to store); a `label` that is not a string is
+   * left off rather than coerced.
+   */
+  async listMetadataItems(type) {
+    await this.connect();
+    const result = await this.client.meta.getItems(type);
+    if (!Array.isArray(result?.items)) {
+      throw new Error(`GET /meta/${type} answered without an items list`);
+    }
+    const out = [];
+    for (const it of result.items) {
+      const name = it?.name;
+      if (typeof name !== "string" || !name) continue;
+      const label = it.label;
+      out.push(typeof label === "string" && label ? { name, label } : { name });
+    }
+    return out;
+  }
   /**
    * Get access to the underlying ObjectStack client for advanced operations.
    */
@@ -3121,14 +4758,16 @@ var ObjectStackAdapter = class {
   invalidateViewKeys(objectName, viewName) {
     this.metadataCache.invalidate?.(`view:${objectName}:${viewName}`);
     this.metadataCache.invalidate?.(`view-overrides:${objectName}`);
+    this.metadataCache.invalidate?.(VIEW_LIST_KEY);
   }
   /**
    * Batch-fetch all persisted view overrides for an object.
    *
    * Per-view runtime overrides (density, column widths, sort, hidden
-   * columns, inlineEdit …) live in the SAME metadata namespace the
-   * write path uses: `type='view'`, `name=<viewId>` (see
-   * {@link updateViewConfig}). Loading them per-view fires N HTTP GETs
+   * columns, inlineEdit …) live in the SAME metadata namespace the view
+   * writes use: `type='view'`, `name=<viewId>` (see {@link createView} /
+   * {@link updateView}; the toolbar's `updateViewConfig` wrote overlays there
+   * until objectui#12504 retired it). Loading them per-view fires N HTTP GETs
    * that 404 for every view the user never customized — console noise on
    * every page load. This batch method performs a single
    * `GET /api/v1/meta/view` (returns `{type, items}`) and narrows the
@@ -3152,9 +4791,9 @@ var ObjectStackAdapter = class {
    *
    * Result is cached identically to {@link getView}, and EVERY view write —
    * on this adapter and above it — invalidates it through the one seam,
-   * {@link invalidateViewKeys}. For a long time only {@link updateViewConfig}
-   * did (objectui#4363), which left the other three adapter paths stale
-   * for the cache's 5-minute TTL. That gap does not self-heal: the consumer
+   * {@link invalidateViewKeys}. For a long time only `updateViewConfig` (since
+   * retired, objectui#12504) did (objectui#4363), which left the other three
+   * adapter paths stale for the cache's 5-minute TTL. That gap does not self-heal: the consumer
    * (`loadViewOverrides`, app-shell `ObjectView`) treats a RESOLVED map as
    * authoritative and deliberately does not re-probe per view — objectui#3774,
    * and correct, since re-probing reinstates the 404 flurry the batch read
@@ -3170,7 +4809,7 @@ var ObjectStackAdapter = class {
     await this.connect();
     const cacheKey = `view-overrides:${objectName}`;
     return await this.metadataCache.get(cacheKey, async () => {
-      const result = await this.client.meta.getItems("view");
+      const result = await this.readViewList();
       const items = Array.isArray(result?.items) ? result.items : Array.isArray(result) ? result : [];
       const out = {};
       for (const it of items) {
@@ -3205,69 +4844,6 @@ var ObjectStackAdapter = class {
       return null;
     }
   }
-  /**
-   * 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}.
-   *
-   * - `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).
-   *
-   * 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, opts) {
-    await this.connect();
-    const merged = {
-      ...config || {},
-      object: config?.object || objectName,
-      name: viewId,
-      ...opts?.isSavedView ? {} : { [VIEW_OVERLAY_MARKER]: true }
-    };
-    const result = await this.client.meta.saveItem(
-      "view",
-      viewId,
-      merged
-    );
-    this.invalidateViewKeys(objectName, viewId);
-    if (result && result.item) return result.item;
-    return result ?? void 0;
-  }
   /**
    * List user-created views for a given object via the metadata overlay
    * API (ADR-0005). Replaces the legacy `find('sys_view', {...})` path
@@ -3279,6 +4855,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();
@@ -3288,7 +4900,7 @@ var ObjectStackAdapter = class {
         const draftItems = await this.metadataClient().withPreviewDrafts(true).list("view");
         items = Array.isArray(draftItems) ? draftItems : [];
       } else {
-        const result = await this.client.meta.getItems("view");
+        const result = await this.readViewList();
         items = Array.isArray(result?.items) ? result.items : Array.isArray(result) ? result : [];
       }
       const FORM_FAMILY = /* @__PURE__ */ new Set(["form", "detail"]);
@@ -3304,18 +4916,35 @@ var ObjectStackAdapter = class {
         const spec = v.list ?? v;
         const isDraft = v._draft === true || spec?._draft === true;
         if (spec && spec.config && typeof spec.config === "object") {
-          return {
+          const row = {
             ...spec.config,
             name: spec.name ?? spec.config.name,
-            label: spec.label ?? spec.config.label,
-            isDefault: !!spec.isDefault,
-            ...isDraft ? { _draft: true } : {}
+            label: spec.label ?? spec.config.label
           };
+          if (spec.object !== void 0) row.object = spec.object;
+          for (const key of VIEW_ITEM_ROUND_TRIP_KEYS) {
+            if (spec[key] !== void 0) row[key] = spec[key];
+          }
+          row.isDefault = !!spec.isDefault;
+          if (isDraft) row._draft = true;
+          return row;
         }
         return isDraft ? { ...spec, _draft: true } : spec;
       });
     } catch (err) {
       console.warn("[OBJECTSTACKDataSource] listViews failed:", err);
+      const failure = classifyViewsFailure(err);
+      if (failure.kind !== "not-served") {
+        this.emitMetadataReadWarning({
+          operation: "listViews",
+          kind: "view",
+          objectName,
+          reason: failure.kind,
+          ...failure.code !== void 0 ? { code: failure.code } : {},
+          ...failure.status !== void 0 ? { status: failure.status } : {},
+          ...failure.message !== void 0 ? { message: failure.message } : {}
+        });
+      }
       return [];
     }
   }
@@ -3334,11 +4963,36 @@ var ObjectStackAdapter = class {
   }
   /**
    * List registered import `mapping` artifacts targeting a given object
-   * (framework #2611). Reads the `mapping` metadata kind via the overlay API
+   * (objectstack-ai/objectstack#2611). Reads the `mapping` metadata kind via the overlay API
    * and filters by `targetObject` client-side (the metadata index is
-   * name-only). Feeds the import wizard's "saved mapping" selector; a failure
-   * (older server without the `mapping` kind) degrades to an empty list, so
-   * the selector simply doesn't appear.
+   * name-only). Feeds the import wizard's "saved mapping" selector.
+   *
+   * ## Every failure still degrades to an empty list — and now says which kind
+   * ## of failure it was (objectui#7741)
+   *
+   * The degrade is unchanged and deliberate: an older server without the
+   * `mapping` kind must not break the wizard, so it keeps answering `[]` and
+   * the selector simply doesn't appear. That is a real, supported deployment
+   * shape and it stays quiet.
+   *
+   * What changed is that the OTHER failures no longer render as that one. A
+   * refused door and a broken one used to be indistinguishable, in the UI, from
+   * "no mapping is registered" — both were an empty list behind a
+   * `console.warn` nothing pointed at — and that silence produced a confident
+   * wrong diagnosis in a careful reporter (objectstack#14026 was filed, routed
+   * and worked by two seats against a wizard that had been correct since
+   * 17.1.0). So the `catch` now asks {@link classifyImportMappingsFailure} what
+   * the failure WAS, reading the error's own ADR-0112 `code` and status —
+   * never "is the result empty", which is what both conditions produce and so
+   * can never tell them apart — and anything that is not the supported
+   * kind-absent shape is announced on {@link onMetadataReadWarning}.
+   *
+   * ⛔ The RETURN is untouched. This method has answered `Promise<any[]>`, never
+   * throwing, since `@object-ui/data-objectstack@17.1.0`; a consumer that reads
+   * nothing new sees exactly what it saw before, including on the loud arms.
+   * Applying framework objectstack#13906 decision 1 option A — *a thing that could not be
+   * READ is not a thing that is ABSENT* — is done by ADDING a channel, not by
+   * moving that contract.
    */
   async listImportMappings(objectName) {
     await this.connect();
@@ -3348,6 +5002,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 [];
     }
   }
@@ -3523,6 +5189,10 @@ var ObjectStackAdapter = class {
    *   the PUBLISHED half after the draft was discarded carries the partial
    *   state on the error's `outcome` — "draft gone, overlay left" is exactly
    *   what the old `{ deleted: boolean }` could not express.
+   *   Its message is the adapter's "NOT fully removed" sentence followed, on
+   *   the next line, by the server's own reason (objectui#12416), so
+   *   `formatMetadataError(err)` shows the remedy a refusal names; the
+   *   original error stays on `cause`.
    *
    * Invalidates through {@link invalidateViewKeys}: the deleted row leaves the
    * batch override map too, and a ghost entry there is what the object page
@@ -3548,9 +5218,12 @@ var ObjectStackAdapter = class {
           draft,
           published: { removed: false }
         };
+        const status = err?.status;
+        const refused = typeof status === "number" && status >= 400 && status < 500;
         throw Object.assign(
           new Error(
-            `deleteView: view "${viewName}" on object "${objectName}" is NOT fully removed \u2014 the draft home was ${draft.removed ? "discarded" : "already absent"}, but deleting the published overlay failed. The published row is still serving the view; retry the delete.`
+            `deleteView: view "${viewName}" on object "${objectName}" is NOT fully removed \u2014 the draft home was ${draft.removed ? "discarded" : "already absent"}, but deleting the published overlay failed. The published row is still serving the view${refused ? "." : "; retry the delete."}
+` + formatMetadataError(err)
           ),
           { cause: err, outcome }
         );
@@ -3602,11 +5275,17 @@ var ObjectStackAdapter = class {
    *
    * The maintainer ruling (2026-08-12) put the answer on the BY-NAME route
    * rather than in the list, so the enumeration surface is not widened past what
-   * a by-name probe already implies (objectstack#8013 / PR #8135): an app that
+   * a by-name probe already implies (objectstack#8013 / PR objectstack-ai/objectstack#8135): an app that
    * exists and whose `requiredPermissions` the session lacks answers `403` with
    * `PERMISSION_DENIED` in the declared envelope, and absence — a nonexistent
-   * name, an unpublished app, an app gated by an absent optional service —
-   * keeps answering `404 RESOURCE_NOT_FOUND`.
+   * name, an unpublished app, an app gated by an absent optional service — is
+   * one undifferentiated answer.
+   *
+   * ⚠️ That absence is NOT uniformly a `404`, which this docstring asserted
+   * until objectui#9262 measured it: the 404 covers an app that EXISTS and is
+   * withheld for a non-permission reason, while a name that resolves to nothing
+   * answers `200` with an envelope carrying no `item`. Both are absence and both
+   * read as `not_found`; see {@link metaEnvelopeCarriesItem} for the measurement.
    *
    * ## Why this is a separate method and not a flavour of {@link getApp}
    *
@@ -3617,19 +5296,68 @@ 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";
+    return (await this.probeMetaItemAccess("app", appName)).verdict;
+  }
+  /**
+   * {@link probeAppAccess} for any metadata type whose by-name read refuses a
+   * caller (objectui#12112): why `name` is not in this session's list of
+   * `type`, plus the server's own sentence when it refused.
+   *
+   * Since objectstack#22731 a dashboard and a list view carry the app's gate:
+   * `GET /api/v1/meta/dashboard` and `/meta/view` list only what the caller may
+   * open, so a withheld item and a missing one are the same absence there, and
+   * the by-name read of one the caller does not hold answers `403`
+   * `PERMISSION_DENIED`, "the app arm's whole refusal (same emitter, same
+   * envelope)". The verdicts are therefore read exactly as for an app.
+   *
+   * `message` is the refusal's `message`, as the server wrote it: the one
+   * sentence that names the item and says it was refused. Only on `denied`.
+   *
+   * Nothing here throws, and nothing is cached: a verdict about the CALLER
+   * must not outlive a grant.
+   *
+   * @param type - the singular metadata type (`app`, `dashboard`, `view`)
+   * @param name - the item's name, as the by-name route addresses it
+   */
+  async probeMetaItemAccess(type, name) {
+    if (!type || !name) return { verdict: "unknown" };
     try {
-      await this.client.meta.getItem("app", appName);
-      return "granted";
+      const envelope = await this.client.meta.getItem(type, name);
+      return { verdict: metaEnvelopeCarriesItem(envelope) ? "granted" : "not_found" };
     } catch (err) {
-      return isAppPermissionDeniedError(err) ? "denied" : "unknown";
+      if (isAppPermissionDeniedError(err)) {
+        const message = err?.message;
+        return typeof message === "string" && message.trim() ? { verdict: "denied", message } : { verdict: "denied" };
+      }
+      if (isMetaItemAbsentError(err)) return { verdict: "not_found" };
+      return { verdict: "unreachable" };
     }
   }
   /**
@@ -3679,7 +5407,8 @@ var ObjectStackAdapter = class {
    * Uses `this.client.analytics.query()` from @objectstack/client to leverage
    * the SDK's built-in auth, headers, and fetch configuration.
    * Falls back to client-side aggregation via find() if the analytics endpoint
-   * is not available.
+   * is not available. Throws {@link AnalyticsResultShapeError} when it answers
+   * with anything but an `AnalyticsResult` carrying `rows`.
    */
   async aggregate(resource, params) {
     await this.connect();
@@ -3688,7 +5417,11 @@ var ObjectStackAdapter = class {
       const queryAst = {};
       if (Array.isArray(params.groupBy)) queryAst.groupBy = params.groupBy;
       if (Array.isArray(params.aggregations)) queryAst.aggregations = params.aggregations;
-      if (params.where !== void 0) queryAst.where = params.where;
+      if (params.where !== void 0) {
+        assertSpecShapeWhereIsFilterAst(params.where, resource);
+        queryAst.where = params.where;
+      }
+      assertNoAnalyticsKeysOnSpecShape(params, resource);
       if (typeof params.limit === "number") queryAst.limit = params.limit;
       const result = await this.client.data.query(resource, queryAst);
       if (Array.isArray(result)) return result;
@@ -3696,6 +5429,7 @@ var ObjectStackAdapter = class {
       if (Array.isArray(result?.data)) return result.data;
       return [];
     }
+    const analyticsWhere = params.filter ? lowerAnalyticsFilterForWire(params.filter, resource) : void 0;
     try {
       const measureName = params.function === "count" ? "count" : `${params.field}_${params.function}`;
       const valueKey = this.aggregateValueKey(params);
@@ -3705,17 +5439,15 @@ 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 measureMissing = rawRows.length > 0 && rawRows.every((row) => {
-        if (row == null) return true;
-        if (measureName in row && row[measureName] != null) return false;
-        if (valueKey in row && row[valueKey] != null) return false;
-        return true;
-      });
+      const rawRows = contractResult.rows;
+      const measureMissing = rawRows.length > 0 && rawRows.every(
+        (row) => row == null || !(measureName in row) && !(valueKey in row)
+      );
       if (measureMissing) {
         return await this.aggregateViaFind(resource, params);
       }
@@ -3728,6 +5460,7 @@ var ObjectStackAdapter = class {
         return mapped;
       });
     } catch (e) {
+      if (e instanceof AnalyticsResultShapeError) throw e;
       const failure = classifyAnalyticsFailure(e);
       if (failure.kind === "rejected") {
         throw new AnalyticsQueryRejectedError(failure.message, failure.code);
@@ -3747,6 +5480,34 @@ var ObjectStackAdapter = class {
       return await this.aggregateViaFind(resource, params);
     }
   }
+  /**
+   * Answer a grouped list view's GROUP HEADER query (objectui#7189) — see
+   * `DataSource.queryGroupHeaders` in `@object-ui/types` for the contract.
+   *
+   * The compiled query rides the platform's EXISTING data door verbatim:
+   * `client.data.query()` posts it to `POST /data/:object/query`, whose
+   * `findData` routes a body carrying `groupBy` / `aggregations` to
+   * `engine.aggregate` and answers the header rows as `records` (the door the
+   * spec half of objectstack#14556 names, pinned platform-side by
+   * objectstack#15330). No new route, no new wire shape.
+   *
+   * ⛔ No fallback, deliberately — unlike {@link aggregate}. A header query that
+   * degraded to bucketing a fetched page would answer page slices under a name
+   * that promises the query's own numbers, which is the defect this member
+   * exists to end. A failure is thrown to the caller, and a body without a
+   * `records` array is refused rather than read as "no groups".
+   */
+  async queryGroupHeaders(resource, query) {
+    await this.connect();
+    const result = await this.client.data.query(resource, query);
+    const records = result?.records;
+    if (!Array.isArray(records)) {
+      throw new Error(
+        `queryGroupHeaders('${resource}'): POST /data/${resource}/query answered without a \`records\` array, so no group header can be read from it. The header query was sent verbatim; nothing was approximated from a page of rows.`
+      );
+    }
+    return records;
+  }
   /**
    * Client-side aggregation over a server-scoped `find()` — the fallback used
    * whenever the analytics endpoint cannot answer (capability absent, network
@@ -3842,6 +5603,13 @@ var ObjectStackAdapter = class {
       if (errorCodeIs({ code: serverCode }, "UNAUTHENTICATED")) {
         throw new AnalyticsUnauthenticatedError({ serverCode, serverMessage });
       }
+      if (errorCodeIs({ code: serverCode }, "PERMISSION_DENIED")) {
+        throw new AnalyticsForbiddenError({
+          serverCode,
+          serverMessage,
+          datasetName: requestedDatasetName
+        });
+      }
       if (serverCode === void 0) {
         if (ANALYTICS_ABSENT_STATUSES.includes(res.status)) {
           throw new AnalyticsNotInstalledError(surface, detail || void 0);
@@ -3982,9 +5750,10 @@ var ObjectStackAdapter = class {
       }
     });
     if (!response.ok) {
-      const error = await response.json().catch(() => ({ message: response.statusText }));
+      const errorBody = await response.json().catch(() => ({ message: response.statusText }));
+      const envelope = readErrorEnvelope(errorBody);
       throw new ObjectStackError(
-        error.message || `Upload failed with status ${response.status}`,
+        envelope.message ?? `Upload failed with status ${response.status}`,
         "UPLOAD_ERROR",
         response.status
       );
@@ -4024,9 +5793,10 @@ var ObjectStackAdapter = class {
       }
     });
     if (!response.ok) {
-      const error = await response.json().catch(() => ({ message: response.statusText }));
+      const errorBody = await response.json().catch(() => ({ message: response.statusText }));
+      const envelope = readErrorEnvelope(errorBody);
       throw new ObjectStackError(
-        error.message || `Upload failed with status ${response.status}`,
+        envelope.message ?? `Upload failed with status ${response.status}`,
         "UPLOAD_ERROR",
         response.status
       );
@@ -4108,29 +5878,50 @@ export {
   API_ACCESS_DENIED_CODES,
   APP_PERMISSION_DENIED_CODE,
   AnalyticsDatasetNotFoundError,
+  AnalyticsForbiddenError,
+  AnalyticsKeysOnSpecShapeError,
   AnalyticsNotInstalledError,
   AnalyticsQueryRejectedError,
+  AnalyticsResultShapeError,
   AnalyticsUnauthenticatedError,
   AuthenticationError,
   BulkOperationError,
+  CHOICE_TYPES_REQUIRING_OPTIONS,
   ConcurrentUpdateError,
   ConnectionError,
   DataApiValidationError,
   FILTER_OPERATOR_ALIASES,
+  META_ITEM_ABSENT_CODE,
   MalformedFilterError,
   MetadataClient,
   MetadataNotFoundError,
+  OBJECT_METADATA_TYPE,
   ObjectStackAdapter,
   ObjectStackError,
+  PREFERENCE_FAMILY_ROW_LIMIT,
+  RELATIONSHIP_TYPES_REQUIRING_REFERENCE,
+  UNRECOGNIZED_DROP_REASON,
+  UnlowerableAnalyticsFilterError,
+  UnloweredAggregateWhereError,
   VIEW_OVERLAY_OWNED_KEYS,
+  assertObjectMetadataWritable,
   classifyAnalyticsFailure,
+  classifyImportMappingsFailure,
+  classifyViewsFailure,
   clearSharedDiscoveryCache,
   createErrorFromResponse,
   createObjectStackAdapter,
+  createObjectStackUserPreferenceFamily,
   createObjectStackUserStateAdapter,
   createQuietHttpLogger,
+  draftChangesUnder,
+  dropServedPicklistOptions,
+  extractDraftBody,
   formatHttpFailureMessage,
+  formatMetadataError,
+  formatMetadataIssue,
   getSharedDiscovery,
+  governingDraftChange,
   is404Error,
   isAnalyticsNotInstalledError,
   isApiAccessDeniedError,
@@ -4138,9 +5929,11 @@ export {
   isConcurrentUpdateError,
   isErrorType,
   isMalformedFilterError,
+  isMetaItemAbsentError,
   isObjectStackError,
   narrowPersonalizationOverlay,
   normaliseClientError,
+  readDraftChanges,
   readSaveAdvisories,
   readTransactionalBatchCapability,
   serializeOrderBy,