@object-ui/data-objectstack 17.3.0 → 17.5.0

package/dist/index.cjs

@@ -22,11 +22,12 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  API_ACCESS_DENIED_CODES: () => API_ACCESS_DENIED_CODES,
+  APP_PERMISSION_DENIED_CODE: () => APP_PERMISSION_DENIED_CODE,
   AnalyticsNotInstalledError: () => AnalyticsNotInstalledError,
   AnalyticsQueryRejectedError: () => AnalyticsQueryRejectedError,
   AuthenticationError: () => AuthenticationError,
   BulkOperationError: () => BulkOperationError,
-  CloudOperations: () => CloudOperations,
   ConcurrentUpdateError: () => ConcurrentUpdateError,
   ConnectionError: () => ConnectionError,
   DataApiValidationError: () => DataApiValidationError,
@@ -45,780 +46,867 @@ __export(index_exports, {
   createErrorFromResponse: () => createErrorFromResponse,
   createObjectStackAdapter: () => createObjectStackAdapter,
   createObjectStackUserStateAdapter: () => createObjectStackUserStateAdapter,
+  createQuietHttpLogger: () => createQuietHttpLogger,
+  formatHttpFailureMessage: () => formatHttpFailureMessage,
   generateContractManifest: () => generateContractManifest,
   getSharedDiscovery: () => getSharedDiscovery,
   is404Error: () => is404Error,
   isAnalyticsNotInstalledError: () => isAnalyticsNotInstalledError,
+  isApiAccessDeniedError: () => isApiAccessDeniedError,
+  isAppPermissionDeniedError: () => isAppPermissionDeniedError,
   isConcurrentUpdateError: () => isConcurrentUpdateError,
   isErrorType: () => isErrorType,
   isMalformedFilterError: () => isMalformedFilterError,
   isObjectStackError: () => isObjectStackError,
   normaliseClientError: () => normaliseClientError,
+  readSaveAdvisories: () => readSaveAdvisories,
   readTransactionalBatchCapability: () => readTransactionalBatchCapability,
   serializeOrderBy: () => serializeOrderBy,
   snapToGrid: () => snapToGrid,
-  validatePluginContract: () => validatePluginContract
+  validatePluginContract: () => validatePluginContract,
+  viewItemObjectName: () => viewItemObjectName
 });
 module.exports = __toCommonJS(index_exports);
 var import_client = require("@objectstack/client");
 
-// ../types/src/index.ts
-var import_spec = require("@objectstack/spec");
-
-// ../types/src/error-code.ts
-function errorCodeIs(err, code) {
-  const raw = err?.code;
-  if (typeof raw !== "string" || raw.length === 0) return false;
-  return raw.toUpperCase() === code.toUpperCase();
+// src/metadata-client.ts
+function readSaveAdvisories(body) {
+  if (!body || typeof body !== "object") return [];
+  const raw = body.advisories;
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((f) => {
+    if (!f || typeof f !== "object") return false;
+    const c = f;
+    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 errorCodeIsAnyOf(err, codes) {
-  return codes.some((c) => errorCodeIs(err, c));
+var META_PREFIX = "/meta";
+var API_PREFIX = "/api/v1";
+function buildBase(config) {
+  const trimmed = config.baseUrl.replace(/\/+$/, "");
+  const scoped = config.environmentId ? `${API_PREFIX}/environments/${encodeURIComponent(config.environmentId)}${META_PREFIX}` : `${API_PREFIX}${META_PREFIX}`;
+  if (/\/api\/v\d+$/i.test(trimmed)) {
+    const stripped = trimmed.replace(/\/api\/v\d+$/i, "");
+    const scopedNoApi = config.environmentId ? `${API_PREFIX}/environments/${encodeURIComponent(config.environmentId)}${META_PREFIX}` : `${API_PREFIX}${META_PREFIX}`;
+    return `${stripped}${scopedNoApi}`;
+  }
+  return `${trimmed}${scoped}`;
 }
-
-// ../core/src/utils/filter-converter.ts
-var import_ui = require("@objectstack/spec/ui");
-var FilterOperatorError = class extends Error {
-  constructor(message) {
-    super(message);
-    __publicField(this, "code", "INVALID_FILTER");
-    __publicField(this, "httpStatus", 400);
-    this.name = "FilterOperatorError";
+async function parseError(res) {
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    body = await res.text().catch(() => void 0);
   }
-};
-function convertOperatorToAST(operator) {
-  const operatorMap = {
-    "$eq": "=",
-    "$ne": "!=",
-    "$gt": ">",
-    "$gte": ">=",
-    "$lt": "<",
-    "$lte": "<=",
-    "$in": "in",
-    "$nin": "nin",
-    "$notin": "nin",
-    "$between": "between",
-    "$contains": "contains",
-    "$notContains": "notcontains",
-    "$notcontains": "notcontains",
-    "$startsWith": "startswith",
-    "$startswith": "startswith",
-    "$endsWith": "endswith",
-    "$endswith": "endswith"
-  };
-  return operatorMap[operator] || null;
+  const bodyObj = body && typeof body === "object" ? body : void 0;
+  const errNode = bodyObj?.error;
+  const message = (errNode && typeof errNode === "object" ? errNode.message : errNode) ?? bodyObj?.message ?? `Metadata request failed: ${res.status} ${res.statusText}`;
+  const err = new Error(String(message));
+  err.status = res.status;
+  err.body = body;
+  const details = errNode && typeof errNode === "object" ? errNode.details : void 0;
+  const issues = details?.issues ?? (errNode && typeof errNode === "object" ? errNode.issues : void 0) ?? bodyObj?.issues;
+  if (Array.isArray(issues)) err.issues = issues;
+  const code = details?.code ?? (errNode && typeof errNode === "object" ? errNode.code : void 0) ?? bodyObj?.code;
+  if (code != null) err.code = String(code);
+  return err;
 }
-function convertFiltersToAST(filter) {
-  const conditions = [];
-  for (const [field, value] of Object.entries(filter)) {
-    if (value === null || value === void 0) continue;
-    if (typeof value === "object" && !Array.isArray(value)) {
-      for (const [operator, operatorValue] of Object.entries(value)) {
-        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.`
-          );
-        }
-        if (operator === "$null") {
-          conditions.push([field, operatorValue ? "is_null" : "is_not_null", true]);
-          continue;
-        }
-        if (operator === "$exists") {
-          conditions.push([field, operatorValue ? "is_not_null" : "is_null", true]);
-          continue;
-        }
-        const astOperator = convertOperatorToAST(operator);
-        if (astOperator) {
-          conditions.push([field, astOperator, operatorValue]);
-        } else {
-          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.`
-          );
-        }
-      }
-    } else {
-      conditions.push([field, "=", value]);
-    }
+function isMetaItemEnvelope(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const env = value;
+  return typeof env.type === "string" && typeof env.name === "string" && "item" in env;
+}
+var MetadataClient = class _MetadataClient {
+  constructor(config) {
+    __publicField(this, "base");
+    __publicField(this, "fetchImpl");
+    __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. */
+    __publicField(this, "onSaveAdvisory");
+    this.base = buildBase(config);
+    this.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
+    this.headers = { Accept: "application/json", ...config.headers ?? {} };
+    this.previewDrafts = config.previewDrafts === true;
+    this.onSaveAdvisory = config.onSaveAdvisory;
   }
-  if (conditions.length === 0) {
-    return filter;
+  /** Update the client's environment scope at runtime. */
+  withEnvironment(environmentId) {
+    return new _MetadataClient({
+      baseUrl: this.base.replace(/\/api\/v\d+(?:\/environments\/[^/]+)?\/meta$/, "").replace(/\/+$/, ""),
+      environmentId,
+      fetch: this.fetchImpl,
+      headers: this.headers,
+      previewDrafts: this.previewDrafts,
+      // #4133: the advisory sink must survive the clone. `useMetadataClient`
+      // routes EVERY environment-scoped console client through here, so
+      // dropping it would silently disable the channel for exactly the
+      // multi-environment tenants the gate is loudest for.
+      ...this.onSaveAdvisory ? { onSaveAdvisory: this.onSaveAdvisory } : {}
+    });
   }
-  if (conditions.length === 1) {
-    return conditions[0];
+  /**
+   * Derive a client whose reads render the draft-overlaid world (or not).
+   * Same base/fetch/headers; used by the app-shell to switch the whole
+   * renderer tree into ADR-0037 preview mode off one URL flag.
+   */
+  withPreviewDrafts(previewDrafts) {
+    if (previewDrafts === this.previewDrafts) return this;
+    const envMatch = this.base.match(/\/api\/v\d+\/environments\/([^/]+)\/meta$/);
+    return new _MetadataClient({
+      baseUrl: this.base.replace(/\/api\/v\d+(?:\/environments\/[^/]+)?\/meta$/, "").replace(/\/+$/, ""),
+      ...envMatch ? { environmentId: decodeURIComponent(envMatch[1]) } : {},
+      fetch: this.fetchImpl,
+      headers: this.headers,
+      previewDrafts,
+      // #4133: carried for the same reason as in `withEnvironment` — preview
+      // mode swaps the whole renderer tree's client, and writes are unaffected
+      // by ADR-0037, so the save door behind this clone still advises.
+      ...this.onSaveAdvisory ? { onSaveAdvisory: this.onSaveAdvisory } : {}
+    });
   }
-  return ["and", ...conditions];
-}
-
-// ../core/src/adapters/batchTransaction.ts
-function idOf(rec) {
-  if (rec == null) return void 0;
-  return rec.id ?? rec._id ?? rec.recordId;
-}
-function resolveRefs(data, results) {
-  const out = {};
-  for (const [key, value] of Object.entries(data)) {
-    if (value && typeof value === "object" && !Array.isArray(value) && typeof value.$ref === "number") {
-      const refIndex = value.$ref;
-      const id = idOf(results[refIndex]);
-      if (id === void 0) {
-        throw new Error(
-          `batchTransaction: field "${key}" references operation ${refIndex}, which has not produced an id (forward or invalid $ref)`
-        );
-      }
-      out[key] = id;
-    } else {
-      out[key] = value;
+  /** 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 out;
-}
-async function emulateBatchTransaction(dataSource, operations) {
-  const results = [];
-  const created = [];
-  try {
-    for (const op of operations) {
-      const action = op.action ?? "create";
-      if (action === "create") {
-        const record = await dataSource.create(
-          op.object,
-          resolveRefs(op.data ?? {}, results)
-        );
-        results.push(record);
-        const id = idOf(record);
-        if (id) created.push({ object: op.object, id });
-      } else if (action === "update") {
-        if (op.id == null) {
-          throw new Error(`batchTransaction: update on "${op.object}" requires an id`);
-        }
-        results.push(
-          await dataSource.update(
-            op.object,
-            op.id,
-            resolveRefs(op.data ?? {}, results)
-          )
-        );
-      } else {
-        if (op.id == null) {
-          throw new Error(`batchTransaction: delete on "${op.object}" requires an id`);
-        }
-        results.push(await dataSource.delete(op.object, op.id));
-      }
-    }
-    return { results };
-  } catch (err) {
-    if (created.length > 0) {
-      await Promise.allSettled(
-        [...created].reverse().map((c) => dataSource.delete(c.object, c.id))
-      );
+  /** List items of a metadata type (e.g. `object`, `field`, `view`). */
+  async list(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;
     }
-    throw err;
+    return [];
   }
-}
-
-// ../core/src/utils/reference-keys.ts
-function normalizeFieldReferenceKeys(fieldDef) {
-  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;
-  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);
-  return schema;
-}
-
-// src/cache/MetadataCache.ts
-var MetadataCache = class {
   /**
-   * Create a new MetadataCache instance
-   * 
-   * @param options - Configuration options
-   * @param options.maxSize - Maximum number of entries (default: 100)
-   * @param options.ttl - Time to live in milliseconds (default: 5 minutes)
+   * List pending DRAFT items (ADR-0033) — what an AI authored but nobody
+   * published yet. `list()` only sees published/active metadata, so a
+   * just-built app package looks empty there; this surfaces the drafts so the
+   * console can show a "pending changes" view and draft-aware package contents.
+   * Optionally narrow by `packageId` and/or `type`. Returns light headers
+   * (no body) carrying `packageId` for grouping.
    */
-  constructor(options = {}) {
-    __publicField(this, "cache");
-    __publicField(this, "inflight");
-    __publicField(this, "maxSize");
-    __publicField(this, "ttl");
-    __publicField(this, "stats");
-    this.cache = /* @__PURE__ */ new Map();
-    this.inflight = /* @__PURE__ */ new Map();
-    this.maxSize = options.maxSize || 100;
-    this.ttl = options.ttl || 5 * 60 * 1e3;
-    this.stats = {
-      hits: 0,
-      misses: 0,
-      evictions: 0,
-      coalesced: 0
-    };
+  async listDrafts(options = {}) {
+    const params = [];
+    if (options.packageId) params.push(`packageId=${encodeURIComponent(options.packageId)}`);
+    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 ?? [];
   }
   /**
-   * Get a value from cache or fetch it using the provided fetcher function
-   * 
-   * @param key - Cache key
-   * @param fetcher - Async function to fetch data if not in cache
-   * @returns Promise resolving to the cached or fetched data
+   * Fetch a single metadata item and return the response body EXACTLY as the
+   * server sent it — envelope and all.
+   *
+   * The one transport both {@link get} (which unwraps) and {@link getDraft}
+   * (which does not) sit on, so the two can differ in what they hand back
+   * without differing in how they ask. Private on purpose: the envelope is a
+   * wire detail, and the two published contracts above are the supported ways
+   * to read an item.
    */
-  async get(key, fetcher) {
-    const now = Date.now();
-    const cached = this.cache.get(key);
-    if (cached) {
-      const age = now - cached.timestamp;
-      if (age < this.ttl) {
-        cached.accessCount++;
-        cached.lastAccessed = now;
-        this.stats.hits++;
-        this.cache.delete(key);
-        this.cache.set(key, cached);
-        return cached.data;
-      } else {
-        this.cache.delete(key);
-      }
-    }
-    const existing = this.inflight.get(key);
-    if (existing) {
-      this.stats.coalesced++;
-      return existing;
-    }
-    this.stats.misses++;
-    const promise = (async () => {
-      try {
-        const data = await fetcher();
-        this.set(key, data);
-        return data;
-      } finally {
-        this.inflight.delete(key);
-      }
-    })();
-    this.inflight.set(key, promise);
-    return promise;
+  async readItemResponse(type, name, options = {}) {
+    const params = [];
+    if (options.state === "draft") params.push("state=draft");
+    else if (this.previewDrafts) params.push("preview=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 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();
   }
   /**
-   * Prime the cache with a pre-fetched value. Useful when a bulk endpoint
-   * (e.g. list of all object schemas) returns data that would otherwise
-   * be fetched again per item.
+   * Get a single metadata item. Returns the unwrapped item CONTENT — the
+   * metadata document itself, so `obj.fields` / `obj.label` are reachable
+   * directly.
+   *
+   * The framework answers `GET /meta/:type/:name` with the spec-declared
+   * envelope `{ type, name, item, …protection fields }`
+   * (`GetMetaItemResponseSchema`; objectstack#5563 collapsed this read to that
+   * ONE shape), so the envelope is unwrapped here — at the client boundary,
+   * once — rather than by each caller.
+   *
+   * **This method used to return the envelope while promising the body**
+   * (objectui#4271). Nothing detected the disagreement, because the test
+   * doubles across the repo were written against this docblock: every consumer
+   * reading `obj.fields` got `undefined` in production and a field list in
+   * unit tests. The visible cost was the entire field half of the permission
+   * matrix reporting "No fields registered for this object." for every object,
+   * plus dead RLS CEL autocomplete, an inert report drill-down and a designer
+   * that saved the envelope back over the object body.
+   *
+   * A response that is NOT the envelope (an older server answering the bare
+   * document, or a body of its own shape) passes through untouched, and `null`
+   * still comes back on 404 to keep the call site ergonomic.
    */
-  prime(key, data) {
-    this.set(key, data);
+  async get(type, name, options = {}) {
+    const resp = await this.readItemResponse(type, name, options);
+    if (isMetaItemEnvelope(resp)) return resp.item ?? null;
+    return resp;
   }
   /**
-   * Set a value in the cache
-   * 
-   * @param key - Cache key
-   * @param data - Data to cache
+   * Read the pending draft body for an item (`?state=draft`). Returns
+   * `null` when there is no draft pending. Draft reads do NOT fall
+   * back to the published overlay or the artifact registry — a `null`
+   * unambiguously means "nothing to publish".
+   *
+   * Note: this method hands back the `{ type, name, item }` envelope the
+   * framework sends, NOT the body — callers read `.item`. That asymmetry with
+   * {@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.
    */
-  set(key, data) {
-    const now = Date.now();
-    if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
-      this.evictLRU();
+  async getDraft(type, name, options = {}) {
+    return this.readItemResponse(type, name, {
+      state: "draft",
+      ...options.packageId ? { packageId: options.packageId } : {}
+    });
+  }
+  /**
+   * Save (PUT) a metadata item. The framework accepts both the bare
+   * item payload and the `{ item: ... }` / `{ metadata: ... }`
+   * envelopes; we send bare for consistency. Pass `mode: 'draft'` to
+   * stage the change without publishing (Studio's "Save" button).
+   */
+  async save(type, name, item, options = {}) {
+    if (!name || !String(name).trim()) {
+      throw new Error(
+        `MetadataClient.save: name must be non-empty (type="${type}"). The PUT /meta/:type/:name route requires a name segment.`
+      );
     }
-    this.cache.set(key, {
-      data,
-      timestamp: now,
-      accessCount: 1,
-      lastAccessed: now
+    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)}`);
+    const qs = params.length ? `?${params.join("&")}` : "";
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}${qs}`;
+    const headers = {
+      ...this.headers,
+      "Content-Type": "application/json"
+    };
+    if (options.ifMatch) headers["If-Match"] = options.ifMatch;
+    if (options.actor) headers["X-Actor"] = options.actor;
+    const res = await this.fetchImpl(url, {
+      method: "PUT",
+      headers,
+      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 {
+      }
+    }
+    return body;
+  }
+  /**
+   * Publish a single pending draft BY REFERENCE — promotes the draft row for
+   * `(type, name)` into the active overlay and drops the draft. Works for ANY
+   * draft, including ones with no `packageId` binding (which the package-scoped
+   * `/packages/:id/publish-drafts` flow cannot reach). Use this to publish the
+   * exact set returned by {@link listDrafts} without needing a package.
+   *
+   * Returns the server result. For `seed` drafts the protocol also materializes
+   * 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.
+   */
+  async publishDraft(type, name) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/publish`;
+    const res = await this.fetchImpl(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;
   }
   /**
-   * Evict the least recently used entry
+   * Get the 3-state layered view of a metadata item (Phase 3a). Returns
+   * `code` (the artifact / fallback default), `overlay` (the saved
+   * customisation, if any), and `effective` (what the runtime sees).
    */
-  evictLRU() {
-    const firstKey = this.cache.keys().next().value;
-    if (firstKey !== void 0) {
-      this.cache.delete(firstKey);
-      this.stats.evictions++;
+  async layered(type, name, options = {}) {
+    const pkg = options.packageId ? `&package=${encodeURIComponent(options.packageId)}` : "";
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}?layers=true${pkg}`;
+    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
+    if (res.status === 404) {
+      return { code: null, overlay: null, overlayScope: null, effective: null };
+    }
+    if (!res.ok) throw await parseError(res);
+    const body = await res.json();
+    const hasEnvelope = body && ("code" in body || "overlay" in body || "effective" in body);
+    if (!hasEnvelope) {
+      return {
+        code: null,
+        overlay: null,
+        overlayScope: null,
+        effective: 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 } : {},
+      ...body.lockDocsUrl !== void 0 ? { lockDocsUrl: body.lockDocsUrl } : {},
+      ...body.provenance !== void 0 ? { provenance: body.provenance } : {},
+      ...body.packageId !== void 0 ? { packageId: body.packageId } : {},
+      ...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 } : {}
+    };
   }
   /**
-   * Invalidate a specific cache entry or all entries
-   * 
-   * @param key - Optional key to invalidate. If omitted, invalidates all entries
+   * Cross-type sweep of load-time validation results — calls
+   * `GET /meta/diagnostics`. Returns every entry the framework
+   * considers invalid (or, when `severity: 'warning'`, also entries
+   * with only warnings).
+   *
+   * Used by the Studio's governance overview page and by the
+   * directory page to show "N invalid" badges per metadata type.
    */
-  invalidate(key) {
-    if (key) {
-      this.cache.delete(key);
-    } else {
-      this.cache.clear();
+  async diagnostics(options = {}) {
+    const params = [];
+    if (options.type) params.push(`type=${encodeURIComponent(options.type)}`);
+    if (options.severity) params.push(`severity=${encodeURIComponent(options.severity)}`);
+    if (options.packageId) params.push(`package=${encodeURIComponent(options.packageId)}`);
+    const qs = params.length ? `?${params.join("&")}` : "";
+    const url = `${this.base}/diagnostics${qs}`;
+    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
+    if (res.status === 404) {
+      return { entries: [], total: 0, scannedTypes: 0, scannedItems: 0, stats: {} };
     }
+    if (!res.ok) throw await parseError(res);
+    const data = await res.json();
+    return {
+      entries: Array.isArray(data.entries) ? data.entries : [],
+      total: typeof data.total === "number" ? data.total : 0,
+      scannedTypes: typeof data.scannedTypes === "number" ? data.scannedTypes : 0,
+      scannedItems: typeof data.scannedItems === "number" ? data.scannedItems : 0,
+      stats: data.stats && typeof data.stats === "object" ? data.stats : {}
+    };
   }
   /**
-   * Clear all cache entries and reset statistics
+   * Find every metadata item that references this one (Phase 3a). Useful
+   * for pre-delete impact analysis: "Are any views pointing at this
+   * object before I drop it?".
    */
-  clear() {
-    this.cache.clear();
-    this.inflight.clear();
-    this.stats = {
-      hits: 0,
-      misses: 0,
-      evictions: 0,
-      coalesced: 0
-    };
+  async references(type, name) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/references`;
+    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
+    if (res.status === 404) return [];
+    if (!res.ok) throw await parseError(res);
+    const data = await res.json();
+    return Array.isArray(data) ? data : data?.items ?? [];
   }
   /**
-   * Get cache statistics
-   * 
-   * @returns Cache statistics including hit rate
+   * Reset a metadata customization overlay back to the artifact default.
+   * 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.
    */
-  getStats() {
-    const total = this.stats.hits + this.stats.misses;
-    const hitRate = total > 0 ? this.stats.hits / total : 0;
-    return {
-      size: this.cache.size,
-      maxSize: this.maxSize,
-      hits: this.stats.hits,
-      misses: this.stats.misses,
-      evictions: this.stats.evictions,
-      coalesced: this.stats.coalesced,
-      hitRate
-    };
+  async reset(type, name, options = {}) {
+    const qs = options.state === "draft" ? "?state=draft" : "";
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}${qs}`;
+    const headers = { ...this.headers };
+    if (options.ifMatch) headers["If-Match"] = options.ifMatch;
+    if (options.actor) headers["X-Actor"] = options.actor;
+    const res = await this.fetchImpl(url, { method: "DELETE", headers });
+    if (!res.ok) throw await parseError(res);
+    return await res.json();
   }
   /**
-   * Get a cached value synchronously without triggering a fetch.
-   * Returns undefined if not in cache or expired.
+   * Promote the pending draft of an item to the active overlay
+   * (POST `/meta/:type/:name/publish`). Returns
+   * `{ 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.
    */
-  getCachedSync(key) {
-    const entry = this.cache.get(key);
-    if (!entry) return void 0;
-    if (this.ttl > 0 && Date.now() - entry.timestamp > this.ttl) {
-      this.cache.delete(key);
-      return void 0;
-    }
-    this.cache.delete(key);
-    this.cache.set(key, entry);
-    this.stats.hits++;
-    return entry.data;
+  async publish(type, name, options = {}) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/publish`;
+    const headers = {
+      ...this.headers,
+      "Content-Type": "application/json"
+    };
+    if (options.actor) headers["X-Actor"] = options.actor;
+    const res = await this.fetchImpl(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(options.message ? { message: options.message } : {})
+    });
+    if (!res.ok) throw await parseError(res);
+    return await res.json();
   }
   /**
-   * Check if a key exists in the cache (and is not expired)
-   * 
-   * @param key - Cache key to check
-   * @returns true if the key exists and is not expired
+   * Restore an item to a previous version (POST `/meta/:type/:name/rollback`).
+   * The server reads the history row at `toVersion`, writes its body back
+   * as the active overlay with `operation_type='revert'`. Returns
+   * `{ success, version, seq, restoredFromVersion, message }`. Throws
+   * `404 version_not_found` for unknown versions and `409 version_not_restorable`
+   * when the target version is a delete tombstone.
    */
-  has(key) {
-    const cached = this.cache.get(key);
-    if (!cached) {
-      return false;
-    }
-    const age = Date.now() - cached.timestamp;
-    if (age >= this.ttl) {
-      this.cache.delete(key);
-      return false;
-    }
-    return true;
-  }
-};
-
-// src/metadata-client.ts
-var META_PREFIX = "/meta";
-var API_PREFIX = "/api/v1";
-function buildBase(config) {
-  const trimmed = config.baseUrl.replace(/\/+$/, "");
-  const scoped = config.environmentId ? `${API_PREFIX}/environments/${encodeURIComponent(config.environmentId)}${META_PREFIX}` : `${API_PREFIX}${META_PREFIX}`;
-  if (/\/api\/v\d+$/i.test(trimmed)) {
-    const stripped = trimmed.replace(/\/api\/v\d+$/i, "");
-    const scopedNoApi = config.environmentId ? `${API_PREFIX}/environments/${encodeURIComponent(config.environmentId)}${META_PREFIX}` : `${API_PREFIX}${META_PREFIX}`;
-    return `${stripped}${scopedNoApi}`;
-  }
-  return `${trimmed}${scoped}`;
-}
-async function parseError(res) {
-  let body;
-  try {
-    body = await res.json();
-  } catch {
-    body = await res.text().catch(() => void 0);
-  }
-  const bodyObj = body && typeof body === "object" ? body : void 0;
-  const errNode = bodyObj?.error;
-  const message = (errNode && typeof errNode === "object" ? errNode.message : errNode) ?? bodyObj?.message ?? `Metadata request failed: ${res.status} ${res.statusText}`;
-  const err = new Error(String(message));
-  err.status = res.status;
-  err.body = body;
-  const details = errNode && typeof errNode === "object" ? errNode.details : void 0;
-  const issues = details?.issues ?? (errNode && typeof errNode === "object" ? errNode.issues : void 0) ?? bodyObj?.issues;
-  if (Array.isArray(issues)) err.issues = issues;
-  const code = details?.code ?? (errNode && typeof errNode === "object" ? errNode.code : void 0) ?? bodyObj?.code;
-  if (code != null) err.code = String(code);
-  return err;
-}
-var MetadataClient = class _MetadataClient {
-  constructor(config) {
-    __publicField(this, "base");
-    __publicField(this, "fetchImpl");
-    __publicField(this, "headers");
-    /** ADR-0037: when true, reads render the draft-overlaid world. */
-    __publicField(this, "previewDrafts");
-    this.base = buildBase(config);
-    this.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
-    this.headers = { Accept: "application/json", ...config.headers ?? {} };
-    this.previewDrafts = config.previewDrafts === true;
-  }
-  /** Update the client's environment scope at runtime. */
-  withEnvironment(environmentId) {
-    return new _MetadataClient({
-      baseUrl: this.base.replace(/\/api\/v\d+(?:\/environments\/[^/]+)?\/meta$/, "").replace(/\/+$/, ""),
-      environmentId,
-      fetch: this.fetchImpl,
-      headers: this.headers,
-      previewDrafts: this.previewDrafts
+  async rollback(type, name, toVersion, options = {}) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/rollback`;
+    const headers = {
+      ...this.headers,
+      "Content-Type": "application/json"
+    };
+    if (options.actor) headers["X-Actor"] = options.actor;
+    const res = await this.fetchImpl(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        toVersion,
+        ...options.message ? { message: options.message } : {}
+      })
     });
+    if (!res.ok) throw await parseError(res);
+    return await res.json();
   }
   /**
-   * Derive a client whose reads render the draft-overlaid world (or not).
-   * Same base/fetch/headers; used by the app-shell to switch the whole
-   * renderer tree into ADR-0037 preview mode off one URL flag.
+   * Compute a structured top-level key diff between two history versions
+   * (GET `/meta/:type/:name/diff?from=&to=`). Returns
+   * `{ added, removed, changed }` where each entry carries a `path` and
+   * the relevant value(s). Useful for "what changed in this draft?" and
+   * pre-rollback previews.
    */
-  withPreviewDrafts(previewDrafts) {
-    if (previewDrafts === this.previewDrafts) return this;
-    const envMatch = this.base.match(/\/api\/v\d+\/environments\/([^/]+)\/meta$/);
-    return new _MetadataClient({
-      baseUrl: this.base.replace(/\/api\/v\d+(?:\/environments\/[^/]+)?\/meta$/, "").replace(/\/+$/, ""),
-      ...envMatch ? { environmentId: decodeURIComponent(envMatch[1]) } : {},
-      fetch: this.fetchImpl,
+  async diff(type, name, fromVersion, toVersion) {
+    const params = new URLSearchParams();
+    if (fromVersion !== void 0) params.set("from", String(fromVersion));
+    if (toVersion !== void 0) params.set("to", String(toVersion));
+    const qs = params.toString();
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/diff${qs ? `?${qs}` : ""}`;
+    const res = await this.fetchImpl(url, {
+      method: "GET",
       headers: this.headers,
-      previewDrafts
+      cache: "no-store"
     });
-  }
-  /** 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 [];
-  }
-  /** List items of a metadata type (e.g. `object`, `field`, `view`). */
-  async list(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 await res.json();
   }
-  /**
-   * List pending DRAFT items (ADR-0033) — what an AI authored but nobody
-   * published yet. `list()` only sees published/active metadata, so a
-   * just-built app package looks empty there; this surfaces the drafts so the
-   * console can show a "pending changes" view and draft-aware package contents.
-   * Optionally narrow by `packageId` and/or `type`. Returns light headers
-   * (no body) carrying `packageId` for grouping.
-   */
-  async listDrafts(options = {}) {
-    const params = [];
-    if (options.packageId) params.push(`packageId=${encodeURIComponent(options.packageId)}`);
-    if (options.type) params.push(`type=${encodeURIComponent(options.type)}`);
-    const qs = params.length ? `?${params.join("&")}` : "";
-    const url = `${this.base}/_drafts${qs}`;
+  /** Fetch the durable history (change log) for one metadata item. */
+  async history(type, name, options = {}) {
+    const params = new URLSearchParams();
+    if (options.sinceSeq !== void 0) params.set("sinceSeq", String(options.sinceSeq));
+    if (options.limit !== void 0) params.set("limit", String(options.limit));
+    const qs = params.toString();
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/history${qs ? `?${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 await res.json();
   }
   /**
-   * Get a single metadata item. Returns the unwrapped item content
-   * (matching the framework REST handler which calls `res.json(item)`).
-   * Returns `null` on 404 to keep the call-site ergonomic.
+   * Fetch the protection-audit trail for one metadata item
+   * (ADR-0010 §3.6 / Phase 4.1). Shows every save/publish/rollback/
+   * delete/reset attempt — allowed, denied, or forced — so the
+   * Studio "审计日志 / Audit log" tab can render who tried what
+   * and whether a lock blocked it.
    */
-  async get(type, name, options = {}) {
-    const params = [];
-    if (options.state === "draft") params.push("state=draft");
-    else if (this.previewDrafts) params.push("preview=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}`;
+  async audit(type, name, options = {}) {
+    const params = new URLSearchParams();
+    if (options.limit !== void 0) params.set("limit", String(options.limit));
+    const qs = params.toString();
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/audit${qs ? `?${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();
   }
-  /**
-   * Read the pending draft body for an item (`?state=draft`). Returns
-   * `null` when there is no draft pending. Draft reads do NOT fall
-   * back to the published overlay or the artifact registry — a `null`
-   * unambiguously means "nothing to publish".
-   *
-   * Note: the framework wraps draft responses in an envelope
-   * `{ type, name, item }` (matching `getMetaItem`); callers should
-   * read `.item` to get the body. The legacy `get()` returns the
-   * unwrapped body, so this method preserves that asymmetry by
-   * returning whatever the server sent.
-   */
-  async getDraft(type, name, options = {}) {
-    return this.get(type, name, { state: "draft", ...options.packageId ? { packageId: options.packageId } : {} });
+};
+
+// ../types/src/index.ts
+var import_spec = require("@objectstack/spec");
+
+// ../types/src/error-code.ts
+function errorCodeIs(err, code) {
+  const raw = err?.code;
+  if (typeof raw !== "string" || raw.length === 0) return false;
+  return raw.toUpperCase() === code.toUpperCase();
+}
+function errorCodeIsAnyOf(err, codes) {
+  return codes.some((c) => errorCodeIs(err, c));
+}
+
+// ../core/src/utils/filter-converter.ts
+var import_ui = require("@objectstack/spec/ui");
+var FilterOperatorError = class extends Error {
+  constructor(message) {
+    super(message);
+    __publicField(this, "code", "INVALID_FILTER");
+    __publicField(this, "httpStatus", 400);
+    this.name = "FilterOperatorError";
   }
-  /**
-   * Save (PUT) a metadata item. The framework accepts both the bare
-   * item payload and the `{ item: ... }` / `{ metadata: ... }`
-   * envelopes; we send bare for consistency. Pass `mode: 'draft'` to
-   * stage the change without publishing (Studio's "Save" button).
-   */
-  async save(type, name, item, options = {}) {
-    if (!name || !String(name).trim()) {
-      throw new Error(
-        `MetadataClient.save: name must be non-empty (type="${type}"). The PUT /meta/:type/:name route requires a name segment.`
+};
+function convertOperatorToAST(operator) {
+  const operatorMap = {
+    "$eq": "=",
+    "$ne": "!=",
+    "$gt": ">",
+    "$gte": ">=",
+    "$lt": "<",
+    "$lte": "<=",
+    "$in": "in",
+    "$nin": "nin",
+    "$notin": "nin",
+    "$between": "between",
+    "$contains": "contains",
+    "$notContains": "notcontains",
+    "$notcontains": "notcontains",
+    "$startsWith": "startswith",
+    "$startswith": "startswith",
+    "$endsWith": "endswith",
+    "$endswith": "endswith"
+  };
+  return operatorMap[operator] || null;
+}
+function convertFiltersToAST(filter) {
+  const conditions = [];
+  for (const [field, value] of Object.entries(filter)) {
+    if (value === null || value === void 0) continue;
+    if (typeof value === "object" && !Array.isArray(value)) {
+      for (const [operator, operatorValue] of Object.entries(value)) {
+        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.`
+          );
+        }
+        if (operator === "$null") {
+          conditions.push([field, operatorValue ? "is_null" : "is_not_null", true]);
+          continue;
+        }
+        if (operator === "$exists") {
+          conditions.push([field, operatorValue ? "is_not_null" : "is_null", true]);
+          continue;
+        }
+        const astOperator = convertOperatorToAST(operator);
+        if (astOperator) {
+          conditions.push([field, astOperator, operatorValue]);
+        } else {
+          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.`
+          );
+        }
+      }
+    } else {
+      conditions.push([field, "=", value]);
+    }
+  }
+  if (conditions.length === 0) {
+    return filter;
+  }
+  if (conditions.length === 1) {
+    return conditions[0];
+  }
+  return ["and", ...conditions];
+}
+
+// ../core/src/adapters/batchTransaction.ts
+function idOf(rec) {
+  if (rec == null) return void 0;
+  return rec.id ?? rec._id ?? rec.recordId;
+}
+function resolveRefs(data, results) {
+  const out = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (value && typeof value === "object" && !Array.isArray(value) && typeof value.$ref === "number") {
+      const refIndex = value.$ref;
+      const id = idOf(results[refIndex]);
+      if (id === void 0) {
+        throw new Error(
+          `batchTransaction: field "${key}" references operation ${refIndex}, which has not produced an id (forward or invalid $ref)`
+        );
+      }
+      out[key] = id;
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+async function emulateBatchTransaction(dataSource, operations) {
+  const results = [];
+  const created = [];
+  try {
+    for (const op of operations) {
+      const action = op.action ?? "create";
+      if (action === "create") {
+        const record = await dataSource.create(
+          op.object,
+          resolveRefs(op.data ?? {}, results)
+        );
+        results.push(record);
+        const id = idOf(record);
+        if (id) created.push({ object: op.object, id });
+      } else if (action === "update") {
+        if (op.id == null) {
+          throw new Error(`batchTransaction: update on "${op.object}" requires an id`);
+        }
+        results.push(
+          await dataSource.update(
+            op.object,
+            op.id,
+            resolveRefs(op.data ?? {}, results)
+          )
+        );
+      } else {
+        if (op.id == null) {
+          throw new Error(`batchTransaction: delete on "${op.object}" requires an id`);
+        }
+        results.push(await dataSource.delete(op.object, op.id));
+      }
+    }
+    return { results };
+  } catch (err) {
+    if (created.length > 0) {
+      await Promise.allSettled(
+        [...created].reverse().map((c) => dataSource.delete(c.object, c.id))
       );
     }
-    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)}`);
-    const qs = params.length ? `?${params.join("&")}` : "";
-    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}${qs}`;
-    const headers = {
-      ...this.headers,
-      "Content-Type": "application/json"
-    };
-    if (options.ifMatch) headers["If-Match"] = options.ifMatch;
-    if (options.actor) headers["X-Actor"] = options.actor;
-    const res = await this.fetchImpl(url, {
-      method: "PUT",
-      headers,
-      body: JSON.stringify(item)
-    });
-    if (!res.ok) throw await parseError(res);
-    return await res.json();
+    throw err;
   }
+}
+
+// ../core/src/utils/reference-keys.ts
+function normalizeFieldReferenceKeys(fieldDef) {
+  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;
+  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);
+  return schema;
+}
+
+// src/cache/MetadataCache.ts
+var MetadataCache = class {
   /**
-   * Publish a single pending draft BY REFERENCE — promotes the draft row for
-   * `(type, name)` into the active overlay and drops the draft. Works for ANY
-   * draft, including ones with no `packageId` binding (which the package-scoped
-   * `/packages/:id/publish-drafts` flow cannot reach). Use this to publish the
-   * exact set returned by {@link listDrafts} without needing a package.
-   *
-   * Returns the server result. For `seed` drafts the protocol also materializes
-   * 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.
+   * Create a new MetadataCache instance
+   * 
+   * @param options - Configuration options
+   * @param options.maxSize - Maximum number of entries (default: 100)
+   * @param options.ttl - Time to live in milliseconds (default: 5 minutes)
    */
-  async publishDraft(type, name) {
-    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/publish`;
-    const res = await this.fetchImpl(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;
+  constructor(options = {}) {
+    __publicField(this, "cache");
+    __publicField(this, "inflight");
+    __publicField(this, "maxSize");
+    __publicField(this, "ttl");
+    __publicField(this, "stats");
+    this.cache = /* @__PURE__ */ new Map();
+    this.inflight = /* @__PURE__ */ new Map();
+    this.maxSize = options.maxSize || 100;
+    this.ttl = options.ttl || 5 * 60 * 1e3;
+    this.stats = {
+      hits: 0,
+      misses: 0,
+      evictions: 0,
+      coalesced: 0
+    };
   }
   /**
-   * Get the 3-state layered view of a metadata item (Phase 3a). Returns
-   * `code` (the artifact / fallback default), `overlay` (the saved
-   * customisation, if any), and `effective` (what the runtime sees).
+   * Get a value from cache or fetch it using the provided fetcher function
+   * 
+   * @param key - Cache key
+   * @param fetcher - Async function to fetch data if not in cache
+   * @returns Promise resolving to the cached or fetched data
    */
-  async layered(type, name, options = {}) {
-    const pkg = options.packageId ? `&package=${encodeURIComponent(options.packageId)}` : "";
-    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}?layers=true${pkg}`;
-    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
-    if (res.status === 404) {
-      return { code: null, overlay: null, overlayScope: null, effective: null };
+  async get(key, fetcher) {
+    const now = Date.now();
+    const cached = this.cache.get(key);
+    if (cached) {
+      const age = now - cached.timestamp;
+      if (age < this.ttl) {
+        cached.accessCount++;
+        cached.lastAccessed = now;
+        this.stats.hits++;
+        this.cache.delete(key);
+        this.cache.set(key, cached);
+        return cached.data;
+      } else {
+        this.cache.delete(key);
+      }
     }
-    if (!res.ok) throw await parseError(res);
-    const body = await res.json();
-    const hasEnvelope = body && ("code" in body || "overlay" in body || "effective" in body);
-    if (!hasEnvelope) {
-      return {
-        code: null,
-        overlay: null,
-        overlayScope: null,
-        effective: body
-      };
+    const existing = this.inflight.get(key);
+    if (existing) {
+      this.stats.coalesced++;
+      return existing;
     }
-    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 } : {},
-      ...body.lockDocsUrl !== void 0 ? { lockDocsUrl: body.lockDocsUrl } : {},
-      ...body.provenance !== void 0 ? { provenance: body.provenance } : {},
-      ...body.packageId !== void 0 ? { packageId: body.packageId } : {},
-      ...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 } : {}
-    };
+    this.stats.misses++;
+    const promise = (async () => {
+      try {
+        const data = await fetcher();
+        this.set(key, data);
+        return data;
+      } finally {
+        this.inflight.delete(key);
+      }
+    })();
+    this.inflight.set(key, promise);
+    return promise;
   }
   /**
-   * Cross-type sweep of load-time validation results — calls
-   * `GET /meta/diagnostics`. Returns every entry the framework
-   * considers invalid (or, when `severity: 'warning'`, also entries
-   * with only warnings).
-   *
-   * Used by the Studio's governance overview page and by the
-   * directory page to show "N invalid" badges per metadata type.
+   * Prime the cache with a pre-fetched value. Useful when a bulk endpoint
+   * (e.g. list of all object schemas) returns data that would otherwise
+   * be fetched again per item.
    */
-  async diagnostics(options = {}) {
-    const params = [];
-    if (options.type) params.push(`type=${encodeURIComponent(options.type)}`);
-    if (options.severity) params.push(`severity=${encodeURIComponent(options.severity)}`);
-    if (options.packageId) params.push(`package=${encodeURIComponent(options.packageId)}`);
-    const qs = params.length ? `?${params.join("&")}` : "";
-    const url = `${this.base}/diagnostics${qs}`;
-    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
-    if (res.status === 404) {
-      return { entries: [], total: 0, scannedTypes: 0, scannedItems: 0, stats: {} };
+  prime(key, data) {
+    this.set(key, data);
+  }
+  /**
+   * Set a value in the cache
+   * 
+   * @param key - Cache key
+   * @param data - Data to cache
+   */
+  set(key, data) {
+    const now = Date.now();
+    if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
+      this.evictLRU();
     }
-    if (!res.ok) throw await parseError(res);
-    const data = await res.json();
-    return {
-      entries: Array.isArray(data.entries) ? data.entries : [],
-      total: typeof data.total === "number" ? data.total : 0,
-      scannedTypes: typeof data.scannedTypes === "number" ? data.scannedTypes : 0,
-      scannedItems: typeof data.scannedItems === "number" ? data.scannedItems : 0,
-      stats: data.stats && typeof data.stats === "object" ? data.stats : {}
-    };
+    this.cache.set(key, {
+      data,
+      timestamp: now,
+      accessCount: 1,
+      lastAccessed: now
+    });
   }
   /**
-   * Find every metadata item that references this one (Phase 3a). Useful
-   * for pre-delete impact analysis: "Are any views pointing at this
-   * object before I drop it?".
+   * Evict the least recently used entry
    */
-  async references(type, name) {
-    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/references`;
-    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
-    if (res.status === 404) return [];
-    if (!res.ok) throw await parseError(res);
-    const data = await res.json();
-    return Array.isArray(data) ? data : data?.items ?? [];
+  evictLRU() {
+    const firstKey = this.cache.keys().next().value;
+    if (firstKey !== void 0) {
+      this.cache.delete(firstKey);
+      this.stats.evictions++;
+    }
   }
   /**
-   * Reset a metadata customization overlay back to the artifact default.
-   * 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.
+   * Invalidate a specific cache entry or all entries
+   * 
+   * @param key - Optional key to invalidate. If omitted, invalidates all entries
    */
-  async reset(type, name, options = {}) {
-    const qs = options.state === "draft" ? "?state=draft" : "";
-    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}${qs}`;
-    const headers = { ...this.headers };
-    if (options.ifMatch) headers["If-Match"] = options.ifMatch;
-    if (options.actor) headers["X-Actor"] = options.actor;
-    const res = await this.fetchImpl(url, { method: "DELETE", headers });
-    if (!res.ok) throw await parseError(res);
-    return await res.json();
+  invalidate(key) {
+    if (key) {
+      this.cache.delete(key);
+    } else {
+      this.cache.clear();
+    }
   }
   /**
-   * Promote the pending draft of an item to the active overlay
-   * (POST `/meta/:type/:name/publish`). Returns
-   * `{ 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.
+   * Clear all cache entries and reset statistics
    */
-  async publish(type, name, options = {}) {
-    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/publish`;
-    const headers = {
-      ...this.headers,
-      "Content-Type": "application/json"
+  clear() {
+    this.cache.clear();
+    this.inflight.clear();
+    this.stats = {
+      hits: 0,
+      misses: 0,
+      evictions: 0,
+      coalesced: 0
     };
-    if (options.actor) headers["X-Actor"] = options.actor;
-    const res = await this.fetchImpl(url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify(options.message ? { message: options.message } : {})
-    });
-    if (!res.ok) throw await parseError(res);
-    return await res.json();
   }
   /**
-   * Restore an item to a previous version (POST `/meta/:type/:name/rollback`).
-   * The server reads the history row at `toVersion`, writes its body back
-   * as the active overlay with `operation_type='revert'`. Returns
-   * `{ success, version, seq, restoredFromVersion, message }`. Throws
-   * `404 version_not_found` for unknown versions and `409 version_not_restorable`
-   * when the target version is a delete tombstone.
+   * Get cache statistics
+   * 
+   * @returns Cache statistics including hit rate
    */
-  async rollback(type, name, toVersion, options = {}) {
-    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/rollback`;
-    const headers = {
-      ...this.headers,
-      "Content-Type": "application/json"
+  getStats() {
+    const total = this.stats.hits + this.stats.misses;
+    const hitRate = total > 0 ? this.stats.hits / total : 0;
+    return {
+      size: this.cache.size,
+      maxSize: this.maxSize,
+      hits: this.stats.hits,
+      misses: this.stats.misses,
+      evictions: this.stats.evictions,
+      coalesced: this.stats.coalesced,
+      hitRate
     };
-    if (options.actor) headers["X-Actor"] = options.actor;
-    const res = await this.fetchImpl(url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify({
-        toVersion,
-        ...options.message ? { message: options.message } : {}
-      })
-    });
-    if (!res.ok) throw await parseError(res);
-    return await res.json();
   }
   /**
-   * Compute a structured top-level key diff between two history versions
-   * (GET `/meta/:type/:name/diff?from=&to=`). Returns
-   * `{ added, removed, changed }` where each entry carries a `path` and
-   * the relevant value(s). Useful for "what changed in this draft?" and
-   * pre-rollback previews.
+   * Get a cached value synchronously without triggering a fetch.
+   * Returns undefined if not in cache or expired.
    */
-  async diff(type, name, fromVersion, toVersion) {
-    const params = new URLSearchParams();
-    if (fromVersion !== void 0) params.set("from", String(fromVersion));
-    if (toVersion !== void 0) params.set("to", String(toVersion));
-    const qs = params.toString();
-    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/diff${qs ? `?${qs}` : ""}`;
-    const res = await this.fetchImpl(url, {
-      method: "GET",
-      headers: this.headers,
-      cache: "no-store"
-    });
-    if (!res.ok) throw await parseError(res);
-    return await res.json();
-  }
-  /** Fetch the durable history (change log) for one metadata item. */
-  async history(type, name, options = {}) {
-    const params = new URLSearchParams();
-    if (options.sinceSeq !== void 0) params.set("sinceSeq", String(options.sinceSeq));
-    if (options.limit !== void 0) params.set("limit", String(options.limit));
-    const qs = params.toString();
-    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/history${qs ? `?${qs}` : ""}`;
-    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
-    if (!res.ok) throw await parseError(res);
-    return await res.json();
+  getCachedSync(key) {
+    const entry = this.cache.get(key);
+    if (!entry) return void 0;
+    if (this.ttl > 0 && Date.now() - entry.timestamp > this.ttl) {
+      this.cache.delete(key);
+      return void 0;
+    }
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+    this.stats.hits++;
+    return entry.data;
   }
   /**
-   * Fetch the protection-audit trail for one metadata item
-   * (ADR-0010 §3.6 / Phase 4.1). Shows every save/publish/rollback/
-   * delete/reset attempt — allowed, denied, or forced — so the
-   * Studio "审计日志 / Audit log" tab can render who tried what
-   * and whether a lock blocked it.
+   * Check if a key exists in the cache (and is not expired)
+   * 
+   * @param key - Cache key to check
+   * @returns true if the key exists and is not expired
    */
-  async audit(type, name, options = {}) {
-    const params = new URLSearchParams();
-    if (options.limit !== void 0) params.set("limit", String(options.limit));
-    const qs = params.toString();
-    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/audit${qs ? `?${qs}` : ""}`;
-    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
-    if (!res.ok) throw await parseError(res);
-    return await res.json();
+  has(key) {
+    const cached = this.cache.get(key);
+    if (!cached) {
+      return false;
+    }
+    const age = Date.now() - cached.timestamp;
+    if (age >= this.ttl) {
+      this.cache.delete(key);
+      return false;
+    }
+    return true;
   }
 };
 
@@ -1009,45 +1097,6 @@ function isErrorType(error, errorClass) {
   return error instanceof errorClass;
 }
 
-// src/cloud.ts
-var CloudOperations = class {
-  constructor(getClient) {
-    __publicField(this, "getClient", getClient);
-  }
-  /**
-   * Deploy an application to the cloud.
-   */
-  async deploy(appId, config) {
-    const client = this.getClient();
-    const result = await client.cloud?.deploy?.(appId, config);
-    return result ?? { deploymentId: `deploy-${Date.now()}`, status: "pending" };
-  }
-  /**
-   * Get deployment status.
-   */
-  async getDeploymentStatus(deploymentId) {
-    const client = this.getClient();
-    const result = await client.cloud?.getDeployment?.(deploymentId);
-    return result ?? { status: "unknown" };
-  }
-  /**
-   * Search marketplace entries.
-   */
-  async searchMarketplace(query, category) {
-    const client = this.getClient();
-    const result = await client.cloud?.marketplace?.search?.({ query, category });
-    return result?.items ?? [];
-  }
-  /**
-   * Install a marketplace plugin.
-   */
-  async installPlugin(pluginId) {
-    const client = this.getClient();
-    const result = await client.cloud?.marketplace?.install?.(pluginId);
-    return result ?? { success: false };
-  }
-};
-
 // src/contracts.ts
 function validatePluginContract(contract) {
   const errors = [];
@@ -1632,6 +1681,17 @@ function is404Error(error) {
   const code = typeof err.code === "string" ? err.code : "";
   return errorCodeIsAnyOf({ code }, ["OBJECT_NOT_FOUND", "RECORD_NOT_FOUND"]);
 }
+var API_ACCESS_DENIED_CODES = [
+  "OBJECT_API_DISABLED",
+  "OBJECT_API_METHOD_NOT_ALLOWED"
+];
+function isApiAccessDeniedError(error) {
+  return errorCodeIsAnyOf(error, API_ACCESS_DENIED_CODES);
+}
+var APP_PERMISSION_DENIED_CODE = "PERMISSION_DENIED";
+function isAppPermissionDeniedError(error) {
+  return errorCodeIs(error, APP_PERMISSION_DENIED_CODE);
+}
 var AnalyticsNotInstalledError = class extends Error {
   constructor(surface, detail) {
     super(
@@ -1716,6 +1776,19 @@ function normaliseClientError(error) {
     message: typeof e.message === "string" ? e.message : void 0
   });
 }
+function formatHttpFailureMessage(message, meta) {
+  if (!meta || typeof meta !== "object") return null;
+  const method = typeof meta.method === "string" && meta.method ? meta.method : void 0;
+  const url = typeof meta.url === "string" && meta.url ? meta.url : void 0;
+  const status = typeof meta.status === "number" ? meta.status : typeof meta.statusCode === "number" ? meta.statusCode : void 0;
+  if (!method && !url && status === void 0) return null;
+  const errBody = meta.error && typeof meta.error === "object" ? meta.error : void 0;
+  const rawCode = typeof meta.code === "string" && meta.code || (errBody && typeof errBody.code === "string" ? errBody.code : void 0);
+  const parts = [method ?? "GET", url ?? "<unknown url>"];
+  parts.push(`-> ${status ?? "no status"}`);
+  if (rawCode) parts.push(`[${rawCode}]`);
+  return `${message}: ${parts.join(" ")}`;
+}
 function createQuietHttpLogger() {
   const isExpected404 = (meta) => {
     if (!meta || typeof meta !== "object") return false;
@@ -1733,12 +1806,15 @@ function createQuietHttpLogger() {
     warn: (message, meta) => console.warn(message, meta ?? ""),
     error: (message, error, meta) => {
       if (isExpected404(meta)) {
-        console.debug(`[ObjectStack] ${message} (suppressed expected 404)`, meta);
+        console.debug(
+          `[ObjectStack] ${formatHttpFailureMessage(message, meta) ?? message} (suppressed expected 404)`,
+          meta
+        );
         return;
       }
-      console.error(message, error ?? "", meta ?? "");
+      console.error(formatHttpFailureMessage(message, meta) ?? message, error ?? "", meta ?? "");
     },
-    fatal: (message, error, meta) => console.error(message, error ?? "", meta ?? ""),
+    fatal: (message, error, meta) => console.error(formatHttpFailureMessage(message, meta) ?? message, error ?? "", meta ?? ""),
     log: (message, ...args) => console.log(message, ...args),
     child: () => logger,
     withTrace: () => logger
@@ -1777,6 +1853,35 @@ function withoutNoOpDrops(droppedFields, sent, stored) {
   }
   return out;
 }
+function viewItemObjectName(item) {
+  const spec = item?.list ?? item;
+  return spec?.data?.object ?? spec?.object ?? spec?.objectName;
+}
+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 spec = body.list ?? body;
+  if (!spec || typeof spec !== "object") return null;
+  return Object.keys(spec).length > 0 ? spec : null;
+}
+function readViewDeleteReceipt(result) {
+  const r = result ?? void 0;
+  return {
+    removed: !!(r?.deleted ?? r?.reset ?? true),
+    ...typeof r?.reset === "boolean" ? { reset: r.reset } : {},
+    ...typeof r?.message === "string" ? { message: r.message } : {}
+  };
+}
+function mergeViewPatch(current, partial, viewName, objectName) {
+  return {
+    ...current,
+    ...partial,
+    name: viewName,
+    object: current?.object || current?.data?.object || objectName
+  };
+}
 var ObjectStackAdapter = class {
   constructor(config) {
     __publicField(this, "client");
@@ -1829,7 +1934,14 @@ var ObjectStackAdapter = class {
     // whose response carried `droppedFields` (framework #3431/#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
+    // through THIS adapter's `ObjectStackClient` whose 200 carried a non-empty
+    // `advisories` array (#4237; backend objectstack#7435). Sibling of the set
+    // 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 import_client.ObjectStackClient({ ...config, logger: createQuietHttpLogger() });
+    this.installSaveAdvisoryInterceptor();
     this.metadataCache = new MetadataCache(config.cache);
     this.autoReconnect = config.autoReconnect ?? true;
     this.maxReconnectAttempts = config.maxReconnectAttempts ?? 3;
@@ -1984,7 +2096,7 @@ var ObjectStackAdapter = class {
         const result = await this.client.data.find(resource, queryOptions);
         return this.normalizeQueryResult(result, params);
       } catch (err) {
-        if (is404Error(err)) {
+        if (!isApiAccessDeniedError(err) && is404Error(err)) {
           this.missingResources.add(resource);
           return { data: [], total: 0 };
         }
@@ -2212,6 +2324,115 @@ var ObjectStackAdapter = class {
       this.writeWarningListeners.delete(callback);
     };
   }
+  /**
+   * Subscribe to metadata save-advisory events — the runtime authoring gate's
+   * 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
+   * 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
+   * `droppedFields` is required and means "fields the write legally stripped",
+   * so carrying advisories on it would either force every existing
+   * `onWriteWarning` consumer to grow a branch or make the event lie about what
+   * happened. The seam's SHAPE is what is reused here — a long-lived instance
+   * with a `subscribe → unsubscribe` registration that `AdapterProvider` wires
+   * once — not its event type.
+   *
+   * Why here and not on the config, which is how the other client class does it
+   * (#4133/#4236): `MetadataClient` is minted per component by
+   * `useMetadataClient`, so it has no instance to subscribe to and its sink
+   * rides the factory. `ObjectStackAdapter` is the opposite — one long-lived
+   * instance per app, already carrying this exact subscription pattern.
+   */
+  onSaveAdvisory(callback) {
+    this.saveAdvisoryListeners.add(callback);
+    return () => {
+      this.saveAdvisoryListeners.delete(callback);
+    };
+  }
+  /**
+   * Notify all save-advisory subscribers. Isolated exactly like
+   * {@link emitWriteWarning}: a throwing listener must neither break the save
+   * nor starve the others.
+   */
+  emitSaveAdvisory(event) {
+    for (const listener of this.saveAdvisoryListeners) {
+      try {
+        listener(event);
+      } catch (err) {
+        console.warn("ObjectStackAdapter: save-advisory listener error", err);
+      }
+    }
+  }
+  /**
+   * Install the ONE emitter for the metadata save door (#4237).
+   *
+   * ## Why this seam, and what it covers
+   *
+   * `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
+   * `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
+   * method once here therefore covers all of them WITHOUT a per-site edit, which
+   * is the whole point — a toast copied into a dozen call sites is the shape
+   * #4133 rejected for the other client class and it is no better here.
+   *
+   * `meta` is an own, writable property assigned per instance in the SDK's
+   * constructor (`this.meta = { … }`), and the client this adapter builds is
+   * never shared, so the wrap is bounded to an object this adapter owns for its
+   * whole lifetime. It is not a prototype or global patch.
+   *
+   * ## Response shape — measured, not assumed
+   *
+   * The two client classes' envelopes coincide at the top level, which is what
+   * makes `readSaveAdvisories` reusable unchanged across both. `SaveMetaItem-
+   * ResponseSchema` puts `advisories` at the body's top level next to
+   * `success` / `version` / `seq` / `state`, and the SDK's `unwrapResponse`
+   * strips its `{ success, data }` envelope only when the body actually HAS a
+   * `data` key — this body does not, so it is returned verbatim. So the same
+   * reader that `MetadataClient.save` uses reads this response correctly, and
+   * the pins in `onSaveAdvisory.test.ts` drive a real SDK client through a fake
+   * `fetch` rather than stubbing `meta`, so that continues to be measured.
+   *
+   * ## Draft-door honesty (D1)
+   *
+   * 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.
+   */
+  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);
+      try {
+        const advisories = readSaveAdvisories(result);
+        if (advisories.length > 0) {
+          this.emitSaveAdvisory({
+            type,
+            name,
+            mode: result?.state === "draft" ? "draft" : "publish",
+            advisories
+          });
+        }
+      } catch (err) {
+        console.warn("ObjectStackAdapter: save-advisory read error", err);
+      }
+      return result;
+    };
+  }
   async create(resource, data) {
     await this.connect();
     try {
@@ -2271,10 +2492,10 @@ var ObjectStackAdapter = class {
         String(id),
         opts?.ifMatch ? { ifMatch: opts.ifMatch } : void 0
       );
-      if (result.deleted) {
+      if (result.success) {
         this.emitMutation({ type: "delete", resource, id });
       }
-      return result.deleted;
+      return result.success;
     } catch (err) {
       throw normaliseClientError(err);
     }
@@ -2817,6 +3038,8 @@ var ObjectStackAdapter = class {
       const errorBody = await res.json().catch(() => ({ message: res.statusText }));
       const err = new Error(errorBody?.error?.message || errorBody?.message || res.statusText);
       err.status = res.status;
+      err.code = errorBody?.code ?? errorBody?.error?.code;
+      err.httpStatus = res.status;
       throw err;
     }
     const body = await res.json();
@@ -3075,42 +3298,109 @@ var ObjectStackAdapter = class {
       return null;
     }
   }
+  /**
+   * **The one place that knows which cache keys a view-row write invalidates.**
+   *
+   * Two reads are cached under view-shaped keys, and both go stale when any
+   * writer touches a view row for `objectName`:
+   *
+   * | reader                     | key                        |
+   * |----------------------------|----------------------------|
+   * | {@link getView}            | `view:{object}:{viewName}` |
+   * | {@link listViewOverrides}  | `view-overrides:{object}`  |
+   *
+   * Every writer routes here rather than restating that pair. The repo has now
+   * paid twice for restatement: objectui#3778 removed five copies of a key
+   * (`views:{object}`) that no reader had ever populated, and objectui#4363
+   * fixed four copies that named only half the live set — and objectui#4373 is
+   * the measured proof that the failure recurs by default, because the console's
+   * real create/publish flow writes these same rows through the ADR-0034
+   * metadata seam and never learned the key list at all. A pin suite can only
+   * guard the writers that exist; a mandatory seam makes the next writer
+   * structurally unable to forget.
+   *
+   * The rule is uniform per WRITE, not per branch: a write to a view row drops
+   * both keys, in that order. Draft-addressed writes over-invalidate on purpose
+   * — both readers enumerate PUBLISHED rows, so a draft write stales neither —
+   * because the costs are not symmetric. An unnecessary invalidation costs one
+   * refetch; a missed one costs up to the cache's 5-minute TTL of stale
+   * overrides, and "which half am I in?" is not a question a future writer
+   * should have to re-answer to stay correct.
+   *
+   * Public because the writers are not all in this class: app-shell's ADR-0034
+   * seam (`runtime-metadata-persistence.ts`) and `MetadataService` write the
+   * same rows through `client.meta` / the `/meta` draft-publish API, and they
+   * reach this adapter as the `dataSource` they were already handed.
+   *
+   * @param objectName - Object the view belongs to (the `{object}` in both keys)
+   * @param viewName - The view's canonical `name` — the identity
+   *   {@link getView} reads back by and {@link listViewOverrides} keys its map
+   *   with. Callers that hold a qualified `<object>.<key>` name pass it as-is:
+   *   it is the row key, not a path to be split.
+   */
+  invalidateViewKeys(objectName, viewName) {
+    this.metadataCache.invalidate?.(`view:${objectName}:${viewName}`);
+    this.metadataCache.invalidate?.(`view-overrides:${objectName}`);
+  }
   /**
    * Batch-fetch all persisted view overrides for an object.
    *
-   * Per-view runtime overrides (density, column widths, sort, …) are
-   * stored in the metadata registry under key `<objectName>/<viewName>`.
-   * Loading them per-view fires N HTTP GETs that return 404 for views
-   * the user has never customized — generates console noise on every
-   * page load. This batch method performs a single
-   * `GET /api/v1/meta/<objectName>` (returns `{type, items}`) and
-   * returns a `{viewName: override}` map. Returns an empty map if the
-   * server doesn't expose the listing or returns no items.
+   * 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
+   * 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
+   * result to `objectName` client-side, exactly as {@link listViews}
+   * does over the same rows (shared accessor: {@link viewItemObjectName}).
+   *
+   * objectui#3774 — this used to enumerate `GET /api/v1/meta/<objectName>`,
+   * putting the OBJECT name in the metadata TYPE slot. That key space is
+   * disjoint from the one the write path lands in, so the batch map came
+   * back empty for every object, forever, and every saved personalization
+   * read back as "setting didn't save".
+   *
+   * FAILURES REJECT — they are not answered as `{}`. An empty map is an
+   * authoritative "this object has no overrides" (callers may trust it and
+   * skip the per-view reads); a transport/permission failure is "I could
+   * not tell", and reporting the two as the same value is what made
+   * ObjectView's per-view {@link getView} fallback unreachable code. When
+   * we cannot tell, we do not pretend we can. Rejections are not cached
+   * (the cache stores on success only), so a transient failure does not
+   * pin an empty answer for the TTL.
    *
-   * Result is cached identically to {@link getView}; saving a view via
-   * {@link updateViewConfig} invalidates the cache.
+   * 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
+   * (`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
+   * exists to remove. So a stale map here is served in full, and the per-view
+   * {@link getView} fallback that would have masked it never runs.
    *
    * @param objectName - Object name (e.g. 'lead')
    * @returns Map keyed by view name with the persisted override config
+   * @throws whatever the metadata transport throws — callers that have a
+   *   per-view fallback should catch and use it.
    */
   async listViewOverrides(objectName) {
     await this.connect();
-    try {
-      const cacheKey = `view-overrides:${objectName}`;
-      return await this.metadataCache.get(cacheKey, async () => {
-        const result = await this.client.meta.getItems(objectName);
-        const items = Array.isArray(result?.items) ? result.items : [];
-        const out = {};
-        for (const it of items) {
-          if (!it || typeof it !== "object") continue;
-          const key = it.name ?? it.id ?? it._name;
-          if (typeof key === "string" && key) out[key] = it;
-        }
-        return out;
-      });
-    } catch {
-      return {};
-    }
+    const cacheKey = `view-overrides:${objectName}`;
+    return await this.metadataCache.get(cacheKey, async () => {
+      const result = await this.client.meta.getItems("view");
+      const items = Array.isArray(result?.items) ? result.items : Array.isArray(result) ? result : [];
+      const out = {};
+      for (const it of items) {
+        if (!it || typeof it !== "object") continue;
+        if (viewItemObjectName(it) !== objectName) continue;
+        const key = it.name;
+        if (typeof key === "string" && key) out[key] = it;
+      }
+      return out;
+    });
   }
   /**
    * Get a view definition for an object.
@@ -3160,10 +3450,7 @@ var ObjectStackAdapter = class {
       viewId,
       merged
     );
-    const cacheKey = `view:${objectName}:${viewId}`;
-    this.metadataCache.invalidate?.(cacheKey);
-    this.metadataCache.invalidate?.(`view-overrides:${objectName}`);
-    this.metadataCache.invalidate?.(`views:${objectName}`);
+    this.invalidateViewKeys(objectName, viewId);
     if (result && result.item) return result.item;
     return result ?? void 0;
   }
@@ -3174,8 +3461,10 @@ var ObjectStackAdapter = class {
    * match the view spec shape.
    *
    * Returns view spec objects with their canonical `name` as identifier.
-   * Filters by `data.object === objectName` (or top-level `object`)
-   * client-side because the metadata index is name-only, not field-typed.
+   * Narrows to one object client-side via {@link viewItemObjectName} —
+   * 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.
    */
   async listViews(objectName, options) {
     await this.connect();
@@ -3192,8 +3481,7 @@ var ObjectStackAdapter = class {
       return items.filter((v) => {
         if (!v) return false;
         const spec = v.list ?? v;
-        const obj = spec?.data?.object ?? spec?.object ?? spec?.objectName;
-        if (obj !== objectName) return false;
+        if (viewItemObjectName(v) !== objectName) return false;
         const viewKind = v.viewKind ?? spec?.viewKind;
         return !(viewKind && FORM_FAMILY.has(viewKind));
       }).map((v) => {
@@ -3254,6 +3542,10 @@ var ObjectStackAdapter = class {
    *
    * Generates a snake_case name if `spec.name` is not provided by appending
    * a short timestamp suffix to the source-name hint.
+   *
+   * Invalidates through {@link invalidateViewKeys}, like every other writer —
+   * see {@link listViewOverrides} for why the batch map is the one that cannot
+   * heal itself (objectui#4363).
    */
   async createView(objectName, spec) {
     await this.connect();
@@ -3273,48 +3565,184 @@ var ObjectStackAdapter = class {
       data: spec?.data || { provider: "object", object: objectName }
     };
     const result = await this.client.meta.saveItem("view", name, fullSpec);
-    this.metadataCache.invalidate?.(`views:${objectName}`);
+    this.invalidateViewKeys(objectName, name);
     if (result && result.item) return result.item;
     return fullSpec;
   }
   /**
    * Apply a partial update to an existing overlay view. Reads the current
-   * overlay (or seeds from artifact), merges, and writes back. ADR-0005
-   * overlay rows store the *full* view document, so partial updates require
-   * a read-merge-write cycle.
+   * document, merges, and writes it back. ADR-0005 overlay rows store the
+   * *full* view document, so partial updates require a read-merge-write cycle.
+   *
+   * **Both halves address the same row (#4139).** A view has two possible
+   * homes and the read must resolve the one the write will target:
+   *
+   * - a pending per-item **draft** (`?state=draft` / `?mode=draft`) — where
+   *   ADR-0034 stages every runtime-created view, so a view made from the `+`
+   *   tab lives ONLY here until an explicit Publish;
+   * - the **published** overlay (`client.meta.getItem` / `saveItem`).
+   *
+   * The draft is probed FIRST, and a hit is merged and written straight back
+   * as a draft. Two things that ordering buys, both load-bearing:
+   *
+   * 1. A draft-only view is no longer invisible to the read. It used to 404,
+   *    and a `catch {}` labelled "treat missing as create-equivalent"
+   *    substituted `current = {}` — so a rename merged onto nothing and went
+   *    out as a `{label, name, object}` partial the server rejects (422),
+   *    while the draft row the UI reads back through `?preview=draft` kept the
+   *    old label. The edit was lost with no error surfaced to the user.
+   * 2. A draft is never bypassed. Writing the published row while a draft is
+   *    pending would put the edit somewhere the draft shadows — and Publish
+   *    would then overwrite it with the pre-edit body, losing the change a
+   *    second time, later, where nothing connects it to this call.
+   *
+   * A draft edit stays a draft: `mode: 'draft'` keeps ADR-0037's guarantee
+   * that nothing the preview shows goes live until Publish. Renaming a
+   * *published* view (no draft pending) is unchanged — it writes the
+   * published overlay, as before.
+   *
+   * **Both halves invalidate through {@link invalidateViewKeys}** (objectui#4363,
+   * #4373) — same call, same key set, so the draft half's deliberate
+   * over-invalidation is the seam's uniform rule rather than a per-branch
+   * decision this method has to keep re-making.
+   *
+   * @throws when the view resolves in neither home, or when either read fails
+   *   for any other reason (network, permission). Both used to be swallowed
+   *   and converted into the bad partial write above; a caller that wants a
+   *   view created should call {@link createView}, which is the operation that
+   *   actually means "create".
    */
   async updateView(objectName, viewName, partial) {
     await this.connect();
-    let current = {};
+    const metaClient = this.metadataClient();
+    const draft = unwrapViewDraft(
+      await metaClient.get("view", viewName, { state: "draft" })
+    );
+    if (draft) {
+      const mergedDraft = mergeViewPatch(draft, partial, viewName, objectName);
+      await metaClient.save("view", viewName, mergedDraft, { mode: "draft" });
+      this.invalidateViewKeys(objectName, viewName);
+      return mergedDraft;
+    }
+    let current;
     try {
       const r = await this.client.meta.getItem("view", viewName);
       current = r && (r.item || r) || {};
       if (current?.list) current = current.list;
-    } catch {
+    } catch (err) {
+      if (is404Error(err)) {
+        throw Object.assign(
+          new Error(
+            `updateView: view "${viewName}" not found on object "${objectName}" \u2014 no pending draft and no published overlay. Use createView() to create one.`
+          ),
+          { cause: err }
+        );
+      }
+      throw err;
     }
-    const merged = {
-      ...current,
-      ...partial,
-      name: viewName,
-      object: current?.object || current?.data?.object || objectName
-    };
+    const merged = mergeViewPatch(current, partial, viewName, objectName);
     const result = await this.client.meta.saveItem("view", viewName, merged);
-    this.metadataCache.invalidate?.(`views:${objectName}`);
-    this.metadataCache.invalidate?.(`view:${objectName}:${viewName}`);
+    this.invalidateViewKeys(objectName, viewName);
     if (result && result.item) return result.item;
     return merged;
   }
   /**
-   * Delete an overlay view (reset to artifact default if one exists, or
-   * remove entirely if it was a user-created view). Routes to
-   * `DELETE /api/v1/meta/view/:name`.
+   * Delete an overlay view — from **every home it has**.
+   *
+   * A view has two possible homes, the same two {@link updateView} addresses:
+   * the pending per-item **draft** (`DELETE /meta/view/:name?state=draft`) and
+   * the **published** overlay (`DELETE /meta/view/:name`). This method used to
+   * issue only the second, and the three cases came out like this (#4479):
+   *
+   * | case               | before                                              |
+   * |--------------------|-----------------------------------------------------|
+   * | draft-only view    | BUG — the published delete answered `reset:false` /  |
+   * |                    | "nothing to delete", the draft survived, and the tab |
+   * |                    | was still there after reload                        |
+   * | published-only     | correct — `reset:true`, tab gone                     |
+   * | published + draft  | ACCIDENTALLY correct — the published row went, so    |
+   * |                    | the tab went; the orphan draft stayed behind        |
+   *
+   * **Why this is not the mechanical mirror of #4139.** `updateView` probes
+   * the draft first and writes back to whichever home the read resolved, and
+   * that is right for an update in all three cases. Copying it here would be
+   * wrong in the third: `persistRuntimeMetadata` (app-shell) stages EVERY
+   * runtime edit as a draft, so "publish a view, then edit it" routinely
+   * produces a pair — and a draft-first-only delete on a pair discards the
+   * draft and leaves the published row serving the view. That is not Delete
+   * view, it is **Discard draft**, a deliberately different operation that
+   * already exists (`discardRuntimeDraft`, documented as "the published
+   * overlay is untouched"). The clean statement of the asymmetry: for an
+   * update, one home is the right home; for a delete, "remove this view" is
+   * satisfied only when NO home is left serving it.
+   *
+   * So both homes are deleted, **draft first**. The order is load-bearing on
+   * the failure path: a fault between the two calls leaves the PUBLISHED
+   * overlay intact, so the view is still served and the operation is cleanly
+   * retryable. The reverse order would strand a draft-only view — which is
+   * precisely the bug shape above.
+   *
+   * **Two blind calls, no probe.** The framework's `deleteMetaItem` answers a
+   * missing home with a **200** carrying `reset:false` (`"No pending draft
+   * for view/x."` / `"No view 'x' found — nothing to delete."`), never a 404,
+   * so there is nothing for a probe to protect against. `updateView` needs its
+   * probe for a different reason — its read must resolve the row the merge
+   * writes back to — and that reason has no counterpart for a delete.
+   *
+   * **One transport, one error contract.** Both halves go through
+   * {@link MetadataClient} (`reset`), the transport that can express the
+   * `?state=` qualifier and the one `updateView`'s draft half already uses.
+   * The published half used to go through `client.meta.deleteItem`; measured,
+   * that issues the byte-identical request (`DELETE
+   * {baseUrl}/api/v1/meta/view/:name`, no environment scoping is configured on
+   * this adapter), so routing it here costs no addressing change and buys a
+   * single `MetadataError` shape across both calls instead of two.
+   *
+   * @returns `deleted` is true only when no home is left serving the view AND
+   *   at least one actually held a row. A view that existed in neither home
+   *   still answers `false`, unchanged. The per-home outcomes are additive:
+   *   a partial result is observable rather than rounded up to `true`.
+   * @throws when either delete fails, matching {@link updateView}'s
+   *   convention of surfacing the fault rather than degrading. A failure of
+   *   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.
+   *
+   * Invalidates through {@link invalidateViewKeys}: the deleted row leaves the
+   * batch override map too, and a ghost entry there is what the object page
+   * would keep applying (objectui#4363). Fired in a `finally`, so it happens
+   * once per call on EVERY outcome including the throw — after a half-failure
+   * the draft row really is gone, and #4363's asymmetry decides it: an
+   * unnecessary invalidation costs one refetch, a missed one costs the cache's
+   * full 5-minute TTL of stale overrides.
    */
   async deleteView(objectName, viewName) {
     await this.connect();
-    const result = await this.client.meta.deleteItem("view", viewName);
-    this.metadataCache.invalidate?.(`views:${objectName}`);
-    this.metadataCache.invalidate?.(`view:${objectName}:${viewName}`);
-    return { deleted: !!(result?.deleted ?? result?.reset ?? true) };
+    const metaClient = this.metadataClient();
+    try {
+      const draft = readViewDeleteReceipt(
+        await metaClient.reset("view", viewName, { state: "draft" })
+      );
+      let published;
+      try {
+        published = readViewDeleteReceipt(await metaClient.reset("view", viewName));
+      } catch (err) {
+        const outcome = {
+          deleted: false,
+          draft,
+          published: { removed: false }
+        };
+        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.`
+          ),
+          { cause: err, outcome }
+        );
+      }
+      return { deleted: draft.removed || published.removed, draft, published };
+    } finally {
+      this.invalidateViewKeys(objectName, viewName);
+    }
   }
   /**
    * Get an application definition by name or ID.
@@ -3338,6 +3766,51 @@ var ObjectStackAdapter = class {
       return null;
     }
   }
+  /**
+   * Ask the by-name meta app route WHY an app is not in this session's app list
+   * (objectui#4252).
+   *
+   * `GET /api/v1/meta/apps` is filtered per session server-side
+   * (`filterAppForUser`), so an app withheld by `requiredPermissions` and an app
+   * that does not exist are byte-identical there: both are simply absent. A
+   * console reading only that list has one fact and two conditions, and it
+   * renders its copy for the wrong one — "it may still be publishing" over a
+   * permanent authorization decision, which cost a downstream acceptance round
+   * two test batches spent chasing a platform defect that was a missing
+   * permission-set binding.
+   *
+   * 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
+   * 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`.
+   *
+   * ## Why this is a separate method and not a flavour of {@link getApp}
+   *
+   *  - `getApp` degrades EVERY failure to `null`, which is exactly the
+   *    conflation this exists to undo; changing it would silently re-point its
+   *    own callers' fallback-to-static-config path.
+   *  - `getApp` memoises in `metadataCache`. A verdict about the CALLER must not
+   *    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).
+   *
+   * @param appName - the app name as it appears in the URL segment
+   */
+  async probeAppAccess(appName) {
+    if (!appName) return "unknown";
+    try {
+      await this.client.meta.getItem("app", appName);
+      return "granted";
+    } catch (err) {
+      return isAppPermissionDeniedError(err) ? "denied" : "unknown";
+    }
+  }
   /**
    * Get a page definition from ObjectStack.
    * Uses the metadata API to fetch page layouts.
@@ -3490,7 +3963,17 @@ var ObjectStackAdapter = class {
    * silently returning wrong numbers.
    *
    * @param dataset - An inline dataset definition (draft) OR a saved dataset name.
-   * @param selection - Dimension/measure names to project + runtime directives.
+   * @param selection - The spec's {@link DatasetSelection} — dimension/measure
+   *   names to project plus runtime directives. This parameter IS the spec type
+   *   by reference, never a local restatement of it (objectui#3613): a hand
+   *   copy of a contract is a second dialect of it, and the copy this replaced
+   *   had already drifted three ways from `@objectstack/spec` — it required
+   *   `compareTo.dimension` (optional since objectstack#5011, and resolved by
+   *   the EXECUTOR, so requiring it pushed callers into exactly the
+   *   consumer-side dimension guess AGENTS.md #0.1 forbids), it widened
+   *   `timeDimensions` to `unknown[]` and `runtimeFilter` to
+   *   `Record<string, unknown>`, and it had never grown `dateGranularity` at
+   *   all. Pinned in `queryDataset.test.ts`.
    */
   async queryDataset(dataset, selection) {
     await this.connect();
@@ -3525,8 +4008,9 @@ var ObjectStackAdapter = class {
     const object = typeof data?.object === "string" ? data.object : void 0;
     const dimensionFields = data?.dimensionFields && typeof data.dimensionFields === "object" ? data.dimensionFields : void 0;
     const drillRawRows = Array.isArray(data?.drillRawRows) ? data.drillRawRows : void 0;
+    const drillRanges = Array.isArray(data?.drillRanges) ? data.drillRanges : void 0;
     const totals = Array.isArray(data?.totals) ? data.totals : void 0;
-    return { rows, fields, object, dimensionFields, drillRawRows, totals };
+    return { rows, fields, object, dimensionFields, drillRawRows, drillRanges, totals };
   }
   /** Client-side aggregation fallback */
   /**
@@ -3771,11 +4255,12 @@ function createObjectStackAdapter(config) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  API_ACCESS_DENIED_CODES,
+  APP_PERMISSION_DENIED_CODE,
   AnalyticsNotInstalledError,
   AnalyticsQueryRejectedError,
   AuthenticationError,
   BulkOperationError,
-  CloudOperations,
   ConcurrentUpdateError,
   ConnectionError,
   DataApiValidationError,
@@ -3794,17 +4279,23 @@ function createObjectStackAdapter(config) {
   createErrorFromResponse,
   createObjectStackAdapter,
   createObjectStackUserStateAdapter,
+  createQuietHttpLogger,
+  formatHttpFailureMessage,
   generateContractManifest,
   getSharedDiscovery,
   is404Error,
   isAnalyticsNotInstalledError,
+  isApiAccessDeniedError,
+  isAppPermissionDeniedError,
   isConcurrentUpdateError,
   isErrorType,
   isMalformedFilterError,
   isObjectStackError,
   normaliseClientError,
+  readSaveAdvisories,
   readTransactionalBatchCapability,
   serializeOrderBy,
   snapToGrid,
-  validatePluginContract
+  validatePluginContract,
+  viewItemObjectName
 });