@object-ui/data-objectstack 17.3.0 → 17.6.0

package/dist/index.cjs

@@ -22,803 +22,910 @@ 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,
+  AnalyticsDatasetNotFoundError: () => AnalyticsDatasetNotFoundError,
   AnalyticsNotInstalledError: () => AnalyticsNotInstalledError,
   AnalyticsQueryRejectedError: () => AnalyticsQueryRejectedError,
+  AnalyticsUnauthenticatedError: () => AnalyticsUnauthenticatedError,
   AuthenticationError: () => AuthenticationError,
   BulkOperationError: () => BulkOperationError,
-  CloudOperations: () => CloudOperations,
   ConcurrentUpdateError: () => ConcurrentUpdateError,
   ConnectionError: () => ConnectionError,
   DataApiValidationError: () => DataApiValidationError,
   FILTER_OPERATOR_ALIASES: () => FILTER_OPERATOR_ALIASES,
-  IntegrationManager: () => IntegrationManager,
   MalformedFilterError: () => MalformedFilterError,
   MetadataClient: () => MetadataClient,
   MetadataNotFoundError: () => MetadataNotFoundError,
   ObjectStackAdapter: () => ObjectStackAdapter,
   ObjectStackError: () => ObjectStackError,
-  SecurityManager: () => SecurityManager,
-  calculateAutoLayout: () => calculateAutoLayout,
+  VIEW_OVERLAY_OWNED_KEYS: () => VIEW_OVERLAY_OWNED_KEYS,
   classifyAnalyticsFailure: () => classifyAnalyticsFailure,
   clearSharedDiscoveryCache: () => clearSharedDiscoveryCache,
-  createDefaultCanvasConfig: () => createDefaultCanvasConfig,
   createErrorFromResponse: () => createErrorFromResponse,
   createObjectStackAdapter: () => createObjectStackAdapter,
   createObjectStackUserStateAdapter: () => createObjectStackUserStateAdapter,
-  generateContractManifest: () => generateContractManifest,
+  createQuietHttpLogger: () => createQuietHttpLogger,
+  formatHttpFailureMessage: () => formatHttpFailureMessage,
   getSharedDiscovery: () => getSharedDiscovery,
   is404Error: () => is404Error,
   isAnalyticsNotInstalledError: () => isAnalyticsNotInstalledError,
+  isApiAccessDeniedError: () => isApiAccessDeniedError,
+  isAppPermissionDeniedError: () => isAppPermissionDeniedError,
   isConcurrentUpdateError: () => isConcurrentUpdateError,
   isErrorType: () => isErrorType,
   isMalformedFilterError: () => isMalformedFilterError,
   isObjectStackError: () => isObjectStackError,
+  narrowPersonalizationOverlay: () => narrowPersonalizationOverlay,
   normaliseClientError: () => normaliseClientError,
+  readSaveAdvisories: () => readSaveAdvisories,
   readTransactionalBatchCapability: () => readTransactionalBatchCapability,
   serializeOrderBy: () => serializeOrderBy,
-  snapToGrid: () => snapToGrid,
-  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 [];
+  }
+  /**
+   * 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}`;
+    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
+    if (!res.ok) throw await parseError(res);
+    const data = await res.json();
+    if (Array.isArray(data)) return data;
+    return data?.drafts ?? data?.data?.drafts ?? [];
+  }
+  /**
+   * Fetch a single metadata item and return the response body EXACTLY as the
+   * 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 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();
   }
-}
-
-// ../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)
+   * 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.
    */
-  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 get(type, name, options = {}) {
+    const resp = await this.readItemResponse(type, name, options);
+    if (isMetaItemEnvelope(resp)) return resp.item ?? null;
+    return resp;
   }
   /**
-   * 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
+   * 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.
    */
-  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;
+  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.stats.misses++;
-    const promise = (async () => {
+    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;
+    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 data = await fetcher();
-        this.set(key, data);
-        return data;
-      } finally {
-        this.inflight.delete(key);
+        const advisories = readSaveAdvisories(body);
+        if (advisories.length > 0) {
+          this.onSaveAdvisory({
+            type,
+            name,
+            mode: options.mode === "draft" ? "draft" : "publish",
+            advisories
+          });
+        }
+      } catch {
       }
-    })();
-    this.inflight.set(key, promise);
-    return promise;
+    }
+    return body;
   }
   /**
-   * 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.
+   * 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.
    */
-  prime(key, data) {
-    this.set(key, data);
+  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;
   }
   /**
-   * Set a value in the cache
-   * 
-   * @param key - Cache key
-   * @param data - Data to cache
+   * Get the 3-state layered view of a metadata item: `code` (the packaged
+   * artifact baseline), `overlay` (the tenant customisation row alone) and
+   * `effective` (the merged value the runtime sees).
+   *
+   * Reads **`GET /meta/:type/:name/layers`** — the path the framework declares
+   * for this projection, with a response schema of its own
+   * (`GetMetaItemLayeredResponseSchema`, objectstack#5882 ruling B). It used to
+   * be reached by hanging a `layers` flag on the ordinary item read, which made
+   * one route answer two unrelated representations while `packages/spec`
+   * declared only one of them. That spelling still answers this same body
+   * inside its deprecation window (the response carries RFC 9745
+   * `Deprecation: true` and an RFC 8288 `Link: rel="successor-version"` back to
+   * this path) and is scheduled for removal upstream, so nothing here may
+   * depend on it — the repo-wide ratchet is
+   * `scripts/__tests__/layered-read-declared-path-4016.test.ts`.
+   *
+   * The request is built here rather than delegated to `@objectstack/client`
+   * because the SDK expresses no layered read in EITHER spelling: the
+   * framework's REST route ledger records this route as `server-only`,
+   * "consumed by objectui over plain HTTP", and whether the SDK should express
+   * it is an open upstream product call.
+   *
+   * One behaviour delta rides along with the path, and it is the server's
+   * choice rather than ours: the retired flag FELL THROUGH to the plain item
+   * read on a backend whose protocol implementation had no layered support,
+   * answering the `{ type, name, item }` envelope. A dedicated path refuses to
+   * answer a different resource under this one's declared shape, so it returns
+   * 501 `NOT_IMPLEMENTED` instead — which surfaces here as a thrown error
+   * rather than a view with `code` and `overlay` silently blank.
    */
-  set(key, data) {
-    const now = Date.now();
-    if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
-      this.evictLRU();
+  async layered(type, name, options = {}) {
+    const qs = options.packageId ? `?package=${encodeURIComponent(options.packageId)}` : "";
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/layers${qs}`;
+    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
+    if (res.status === 404) {
+      return { code: null, overlay: null, overlayScope: null, effective: null };
     }
-    this.cache.set(key, {
-      data,
-      timestamp: now,
-      accessCount: 1,
-      lastAccessed: now
-    });
+    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 } : {}
+    };
   }
   /**
-   * Evict the least recently used entry
+   * 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.
    */
-  evictLRU() {
-    const firstKey = this.cache.keys().next().value;
-    if (firstKey !== void 0) {
-      this.cache.delete(firstKey);
-      this.stats.evictions++;
+  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 : {}
+    };
   }
   /**
-   * Invalidate a specific cache entry or all entries
-   * 
-   * @param key - Optional key to invalidate. If omitted, invalidates all entries
+   * 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?".
    */
-  invalidate(key) {
-    if (key) {
-      this.cache.delete(key);
-    } else {
-      this.cache.clear();
-    }
+  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 ?? [];
   }
   /**
-   * Clear all cache entries and reset statistics
+   * 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.
+   */
+  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;
+    const res = await this.fetchImpl(url, { method: "DELETE", headers });
+    if (!res.ok) throw await parseError(res);
+    return await res.json();
+  }
+  /**
+   * 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() {
-    this.cache.clear();
-    this.inflight.clear();
-    this.stats = {
-      hits: 0,
-      misses: 0,
-      evictions: 0,
-      coalesced: 0
+  async publish(type, name, options = {}) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/publish`;
+    const headers = {
+      ...this.headers,
+      "Content-Type": "application/json"
     };
+    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();
   }
   /**
-   * Get cache statistics
-   * 
-   * @returns Cache statistics including hit rate
+   * 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.
    */
-  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 rollback(type, name, toVersion, options = {}) {
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/rollback`;
+    const headers = {
+      ...this.headers,
+      "Content-Type": "application/json"
     };
+    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();
   }
   /**
-   * Get a cached value synchronously without triggering a fetch.
-   * Returns undefined if not in cache or expired.
+   * 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.
    */
-  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 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();
   }
   /**
-   * 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
+   * 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.
    */
-  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;
+  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();
   }
 };
 
-// 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}`;
+// ../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();
 }
-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;
+function errorCodeIsAnyOf(err, codes) {
+  return codes.some((c) => errorCodeIs(err, c));
 }
-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
-    });
-  }
-  /**
-   * 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
-    });
+
+// ../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";
   }
-  /** 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 }));
+};
+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]);
     }
-    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 [];
+  if (conditions.length === 0) {
+    return filter;
   }
-  /**
-   * 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}`;
-    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 ?? [];
+  if (conditions.length === 1) {
+    return conditions[0];
   }
-  /**
-   * 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.
-   */
-  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}`;
-    const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
-    if (res.status === 404) return null;
-    if (!res.ok) throw await parseError(res);
-    return await res.json();
+  return ["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;
+    }
   }
-  /**
-   * 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 } : {} });
+  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))
+      );
+    }
+    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 {
   /**
-   * 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).
+   * 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 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.`
-      );
-    }
-    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"
+  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
     };
-    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();
   }
   /**
-   * 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.
+   * 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 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;
+  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;
   }
   /**
-   * 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).
+   * 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 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 } : {}
-    };
+  prime(key, data) {
+    this.set(key, data);
   }
   /**
-   * 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.
+   * Set a value in the cache
+   * 
+   * @param key - Cache key
+   * @param data - Data to cache
    */
-  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: {} };
+  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,91 +1116,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 = [];
-  const warnings = [];
-  if (!contract.name || contract.name.trim().length === 0) {
-    errors.push({ field: "name", message: "Plugin name is required", code: "MISSING_NAME" });
-  }
-  if (!contract.version || !/^\d+\.\d+\.\d+/.test(contract.version)) {
-    errors.push({ field: "version", message: "Valid semver version is required", code: "INVALID_VERSION" });
-  }
-  if (!contract.exports || contract.exports.length === 0) {
-    errors.push({ field: "exports", message: "At least one export is required", code: "NO_EXPORTS" });
-  }
-  if (contract.exports) {
-    const validTypes = ["component", "hook", "utility", "provider"];
-    for (const exp of contract.exports) {
-      if (!exp.name) {
-        errors.push({ field: "exports.name", message: "Export name is required", code: "MISSING_EXPORT_NAME" });
-      }
-      if (!validTypes.includes(exp.type)) {
-        errors.push({ field: "exports.type", message: `Invalid export type: ${exp.type}`, code: "INVALID_EXPORT_TYPE" });
-      }
-    }
-  }
-  if (!contract.permissions || contract.permissions.length === 0) {
-    warnings.push("No permissions declared \u2014 plugin will have minimal access");
-  }
-  return { valid: errors.length === 0, errors, warnings };
-}
-function generateContractManifest(contract) {
-  return {
-    $schema: "https://objectui.org/schemas/plugin-contract-v1.json",
-    name: contract.name,
-    version: contract.version,
-    peerDependencies: contract.peerDependencies ?? {},
-    exports: contract.exports.map((exp) => ({
-      name: exp.name,
-      type: exp.type,
-      description: exp.description ?? ""
-    })),
-    permissions: contract.permissions ?? [],
-    api: contract.api ?? {},
-    generatedAt: (/* @__PURE__ */ new Date()).toISOString()
-  };
-}
-
 // src/userState.ts
 var DEFAULT_RESOURCE = "sys_user_preference";
 function createObjectStackUserStateAdapter(options) {
@@ -1196,267 +1218,6 @@ function createObjectStackUserStateAdapter(options) {
   };
 }
 
-// src/integration.ts
-var IntegrationManager = class {
-  constructor() {
-    __publicField(this, "integrations", /* @__PURE__ */ new Map());
-  }
-  /**
-   * Register a new integration.
-   */
-  register(id, config) {
-    this.integrations.set(id, config);
-  }
-  /**
-   * Remove an integration.
-   */
-  unregister(id) {
-    this.integrations.delete(id);
-  }
-  /**
-   * Get all registered integrations.
-   */
-  getAll() {
-    return new Map(this.integrations);
-  }
-  /**
-   * Get integrations that match a specific event.
-   */
-  getForEvent(event) {
-    return Array.from(this.integrations.values()).filter(
-      (integration) => integration.enabled && integration.triggers?.some((t) => t.event === event)
-    );
-  }
-  /**
-   * Dispatch an event to all matching integrations.
-   * Returns results for each integration.
-   */
-  async dispatch(event, payload) {
-    const matching = this.getForEvent(event);
-    const results = [];
-    for (const [id, integration] of this.integrations) {
-      if (!matching.includes(integration)) continue;
-      try {
-        await this.send(integration, payload);
-        results.push({ id, success: true });
-      } catch (err) {
-        results.push({ id, success: false, error: err.message });
-      }
-    }
-    return results;
-  }
-  /**
-   * Send payload to a specific integration.
-   */
-  async send(integration, payload) {
-    switch (integration.provider) {
-      case "webhook": {
-        const cfg = integration.config;
-        const url = cfg.url;
-        try {
-          const parsed = new URL(url);
-          if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-            throw new Error(`Invalid URL protocol: ${parsed.protocol}`);
-          }
-        } catch (e) {
-          if (e instanceof TypeError) {
-            throw new Error(`Invalid webhook URL: ${url}`);
-          }
-          throw e;
-        }
-        await fetch(url, {
-          method: cfg.method,
-          headers: {
-            "Content-Type": "application/json",
-            ...cfg.headers
-          },
-          body: JSON.stringify(payload)
-        });
-        break;
-      }
-      case "slack": {
-        const cfg = integration.config;
-        const url = cfg.webhookUrl;
-        try {
-          const parsed = new URL(url);
-          if (parsed.protocol !== "https:") {
-            throw new Error(`Invalid Slack webhook URL protocol: ${parsed.protocol}`);
-          }
-        } catch (e) {
-          if (e instanceof TypeError) {
-            throw new Error(`Invalid Slack webhook URL: ${url}`);
-          }
-          throw e;
-        }
-        await fetch(url, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({
-            channel: cfg.channel,
-            username: cfg.username,
-            icon_emoji: cfg.iconEmoji,
-            text: JSON.stringify(payload)
-          })
-        });
-        break;
-      }
-      // Email and other providers would require server-side implementation
-      default:
-        break;
-    }
-  }
-};
-
-// src/security.ts
-var SecurityManager = class {
-  constructor(policy = {}) {
-    __publicField(this, "policy");
-    __publicField(this, "auditLog", []);
-    this.policy = policy;
-  }
-  /**
-   * Generate a CSP header string from the configuration.
-   */
-  generateCSPHeader() {
-    const csp = this.policy.csp;
-    if (!csp) return "";
-    const directives = [];
-    if (csp.scriptSrc?.length) directives.push(`script-src ${csp.scriptSrc.join(" ")}`);
-    if (csp.styleSrc?.length) directives.push(`style-src ${csp.styleSrc.join(" ")}`);
-    if (csp.imgSrc?.length) directives.push(`img-src ${csp.imgSrc.join(" ")}`);
-    if (csp.connectSrc?.length) directives.push(`connect-src ${csp.connectSrc.join(" ")}`);
-    if (csp.fontSrc?.length) directives.push(`font-src ${csp.fontSrc.join(" ")}`);
-    if (csp.frameSrc?.length) directives.push(`frame-src ${csp.frameSrc.join(" ")}`);
-    if (csp.reportUri) directives.push(`report-uri ${csp.reportUri}`);
-    return directives.join("; ");
-  }
-  /**
-   * Record an audit log entry.
-   */
-  recordAudit(entry) {
-    if (!this.policy.auditLog?.enabled) return;
-    if (this.policy.auditLog.events && !this.policy.auditLog.events.includes(entry.event)) return;
-    const fullEntry = {
-      ...entry,
-      timestamp: (/* @__PURE__ */ new Date()).toISOString()
-    };
-    this.auditLog.push(fullEntry);
-    const dest = this.policy.auditLog.destination ?? "console";
-    if (dest === "console" || dest === "both") {
-      console.info("[AUDIT]", fullEntry.event, fullEntry.userId, fullEntry.resource ?? "");
-    }
-  }
-  /**
-   * Get audit log entries.
-   */
-  getAuditLog(filter) {
-    let entries = [...this.auditLog];
-    if (filter?.event) entries = entries.filter((e) => e.event === filter.event);
-    if (filter?.userId) entries = entries.filter((e) => e.userId === filter.userId);
-    if (filter?.since) entries = entries.filter((e) => e.timestamp >= filter.since);
-    return entries;
-  }
-  /**
-   * Apply data masking to a record.
-   */
-  maskRecord(record, userRoles = []) {
-    if (!this.policy.dataMasking?.rules?.length) return record;
-    const masked = { ...record };
-    const maskChar = this.policy.dataMasking.maskChar ?? "*";
-    for (const rule of this.policy.dataMasking.rules) {
-      if (!(rule.field in masked) || masked[rule.field] == null) continue;
-      if (rule.exemptRoles?.some((role) => userRoles.includes(role))) continue;
-      const value = String(masked[rule.field]);
-      switch (rule.strategy) {
-        case "full":
-          masked[rule.field] = maskChar.repeat(value.length);
-          break;
-        case "partial": {
-          const visible = rule.visibleChars ?? 4;
-          if (value.length <= visible) {
-            masked[rule.field] = maskChar.repeat(value.length);
-          } else {
-            masked[rule.field] = value.slice(0, visible) + maskChar.repeat(value.length - visible);
-          }
-          break;
-        }
-        case "hash":
-          masked[rule.field] = `[HASHED:${simpleHash(value)}]`;
-          break;
-        case "redact":
-          masked[rule.field] = "[REDACTED]";
-          break;
-      }
-    }
-    return masked;
-  }
-  /**
-   * Update the security policy.
-   */
-  updatePolicy(policy) {
-    this.policy = { ...this.policy, ...policy };
-  }
-  /**
-   * Get current security policy.
-   */
-  getPolicy() {
-    return { ...this.policy };
-  }
-};
-function simpleHash(str) {
-  let hash = 0;
-  for (let i = 0; i < str.length; i++) {
-    const char = str.charCodeAt(i);
-    hash = (hash << 5) - hash + char;
-    hash = hash & hash;
-  }
-  return Math.abs(hash).toString(36);
-}
-
-// src/studio.ts
-function createDefaultCanvasConfig(overrides) {
-  return {
-    width: 1200,
-    height: 800,
-    background: "grid",
-    gridSize: 8,
-    snapToGrid: true,
-    zoom: {
-      min: 0.25,
-      max: 3,
-      step: 0.1,
-      current: 1
-    },
-    panOffset: { x: 0, y: 0 },
-    showMinimap: false,
-    minimapPosition: "bottom-right",
-    ...overrides
-  };
-}
-function snapToGrid(x, y, gridSize) {
-  return {
-    x: Math.round(x / gridSize) * gridSize,
-    y: Math.round(y / gridSize) * gridSize
-  };
-}
-function calculateAutoLayout(items, canvasWidth, padding = 40, gap = 40) {
-  const positions = [];
-  let currentX = padding;
-  let currentY = padding;
-  let rowMaxHeight = 0;
-  for (const item of items) {
-    if (currentX + item.width + padding > canvasWidth) {
-      currentX = padding;
-      currentY += rowMaxHeight + gap;
-      rowMaxHeight = 0;
-    }
-    positions.push({ id: item.id, x: currentX, y: currentY });
-    currentX += item.width + gap;
-    rowMaxHeight = Math.max(rowMaxHeight, item.height);
-  }
-  return positions;
-}
-
 // src/index.ts
 var FILTER_OPERATOR_ALIASES = {
   equals: "=",
@@ -1484,6 +1245,15 @@ var FILTER_OPERATOR_ALIASES = {
   notin: "nin",
   nin: "nin",
   contains: "contains",
+  // Case-insensitive contains. A canonical `VIEW_FILTER_OPERATORS` member that
+  // arrived with `@objectstack/spec` 17.1.0 (objectui#5328), and an IDENTITY row
+  // like `contains` above: `icontains` is itself a member of
+  // `VALID_AST_OPERATORS`, so the spelling the author writes is the spelling the
+  // AST takes — nothing is translated and no case-sensitivity is lost.
+  // Declared rather than left to the `?? op` fall-through on the rule this
+  // table's test states: the AST gate accepting a spelling is not the driver
+  // compiling it into a WHERE clause.
+  icontains: "icontains",
   not_contains: "notcontains",
   notcontains: "notcontains",
   starts_with: "startswith",
@@ -1632,22 +1402,95 @@ 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) {
+  constructor(surface, detail, serverCode) {
     super(
       `Analytics capability is not installed on this deployment \u2014 ${surface} is unavailable. Install @objectstack/service-analytics and mount AnalyticsServicePlugin to enable it.` + (detail ? ` (server said: ${detail})` : "")
     );
     __publicField(this, "code", "ANALYTICS_NOT_INSTALLED");
     /** The surface that was unavailable, for the message a host renders. */
     __publicField(this, "surface");
+    /**
+     * The server's own ADR-0112 code — the field this branch was chosen BY, when
+     * a producer named one (`NOT_IMPLEMENTED` from the mounted route with no
+     * service behind it, `ROUTE_NOT_FOUND` from the dispatcher when the route is
+     * not mounted at all). Absent for the no-code residual, where a bare
+     * transport 404/501 is all there was to read.
+     *
+     * Additive (objectui#5663): carried so a reader can audit that the headline
+     * and the quoted `detail` below came off the same answer.
+     */
+    __publicField(this, "serverCode");
     this.name = "AnalyticsNotInstalledError";
     this.surface = surface;
+    this.serverCode = serverCode;
   }
 };
 function isAnalyticsNotInstalledError(error) {
   if (!error || typeof error !== "object") return false;
   return error.code === "ANALYTICS_NOT_INSTALLED";
 }
+var AnalyticsDatasetNotFoundError = class extends Error {
+  constructor(opts) {
+    const subject = opts.datasetName ? `Dataset "${opts.datasetName}"` : "The requested dataset";
+    super(
+      `${subject} is not defined in this environment \u2014 the app that defines it is missing or out of date. Analytics itself is installed and answering, so the fix is to upgrade the installed app, not to install a server plugin.` + (opts.serverMessage ? ` (server said: ${opts.serverMessage})` : "")
+    );
+    __publicField(this, "code", "ANALYTICS_DATASET_NOT_FOUND");
+    /**
+     * The dataset this query asked for, taken from the REQUEST rather than parsed
+     * back out of the server's prose: the request is what we know for certain,
+     * and re-reading the name out of a message would make the headline depend on
+     * that message's WORDING — the coupling framework#5367 spent a whole issue
+     * removing from the producing route.
+     */
+    __publicField(this, "datasetName");
+    /** The server's own ADR-0112 code — the field this branch was chosen BY. */
+    __publicField(this, "serverCode");
+    /** The server's own message, quoted verbatim in the parenthetical. */
+    __publicField(this, "serverMessage");
+    this.name = "AnalyticsDatasetNotFoundError";
+    this.datasetName = opts.datasetName;
+    this.serverCode = opts.serverCode;
+    this.serverMessage = opts.serverMessage;
+  }
+};
+var AnalyticsUnauthenticatedError = class extends Error {
+  constructor(opts = {}) {
+    super(
+      "Analytics query refused: this session is not authenticated. Sign in again and retry \u2014 the request was refused before it ran, so it says nothing about whether the analytics capability is installed." + (opts.serverMessage ? ` (server said: ${opts.serverMessage})` : "")
+    );
+    __publicField(this, "code", "ANALYTICS_UNAUTHENTICATED");
+    /** The server's own ADR-0112 code — the field this branch was chosen BY. */
+    __publicField(this, "serverCode");
+    /** The server's own message, quoted verbatim in the parenthetical. */
+    __publicField(this, "serverMessage");
+    this.name = "AnalyticsUnauthenticatedError";
+    this.serverCode = opts.serverCode;
+    this.serverMessage = opts.serverMessage;
+  }
+};
+function readAnalyticsErrorEnvelope(body) {
+  if (!body || typeof body !== "object") return {};
+  const flat = body;
+  const wrapped = flat.error && typeof flat.error === "object" ? flat.error : void 0;
+  const source = wrapped ?? flat;
+  const code = typeof source.code === "string" && source.code.length > 0 ? source.code : void 0;
+  const message = typeof source.message === "string" && source.message.length > 0 ? source.message : typeof flat.error === "string" && flat.error.length > 0 ? flat.error : void 0;
+  return { code, message };
+}
+var ANALYTICS_ABSENT_STATUSES = [404, 501];
 var AnalyticsQueryRejectedError = class extends Error {
   constructor(detail, serverCode) {
     super(
@@ -1662,13 +1505,22 @@ var AnalyticsQueryRejectedError = class extends Error {
 };
 function classifyAnalyticsFailure(error) {
   const err = error ?? {};
-  const code = typeof err.code === "string" ? err.code : void 0;
+  const code = typeof err.code === "string" && err.code.length > 0 ? err.code : void 0;
   const message = typeof err.message === "string" ? err.message : void 0;
   const status = typeof err.httpStatus === "number" ? err.httpStatus : typeof err.status === "number" ? err.status : typeof err.statusCode === "number" ? err.statusCode : void 0;
-  if (code === "VALIDATION_FAILED" || status === 400) return { kind: "rejected", code, message };
-  if (status === 404 || status === 501 || code === "NOT_IMPLEMENTED" || code === "ROUTE_NOT_FOUND") {
+  if (errorCodeIsAnyOf({ code }, ["NOT_IMPLEMENTED", "ROUTE_NOT_FOUND"])) {
     return { kind: "not-installed", code, message };
   }
+  if (errorCodeIs({ code }, "VALIDATION_FAILED")) return { kind: "rejected", code, message };
+  if (errorCodeIs({ code }, "UNAUTHENTICATED")) return { kind: "unauthenticated", code, message };
+  if (errorCodeIs({ code }, "CUBE_NOT_FOUND")) return { kind: "cube-not-found", code, message };
+  if (code === void 0) {
+    if (status !== void 0 && ANALYTICS_ABSENT_STATUSES.includes(status)) {
+      return { kind: "not-installed", code, message };
+    }
+    if (status === 400) return { kind: "rejected", code, message };
+    if (status === 401) return { kind: "unauthenticated", code, message };
+  }
   return { kind: "unknown", code, message };
 }
 var ConcurrentUpdateError = class extends Error {
@@ -1716,6 +1568,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;
@@ -1728,17 +1593,27 @@ function createQuietHttpLogger() {
     return false;
   };
   const logger = {
-    debug: (message, meta) => console.debug(message, meta ?? ""),
-    info: (message, meta) => console.info(message, meta ?? ""),
+    debug: (message, meta) => (
+      // eslint-disable-next-line no-console -- objectui#4029, see comment above
+      console.debug(message, meta ?? "")
+    ),
+    info: (message, meta) => (
+      // eslint-disable-next-line no-console -- objectui#4029, see comment above
+      console.info(message, meta ?? "")
+    ),
     warn: (message, meta) => console.warn(message, meta ?? ""),
     error: (message, error, meta) => {
       if (isExpected404(meta)) {
-        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 ?? ""),
+    // eslint-disable-next-line no-console -- objectui#4029, see comment above
     log: (message, ...args) => console.log(message, ...args),
     child: () => logger,
     withTrace: () => logger
@@ -1777,6 +1652,73 @@ function withoutNoOpDrops(droppedFields, sent, stored) {
   }
   return out;
 }
+function viewItemObjectName(item) {
+  const spec = item?.list ?? item;
+  return spec?.data?.object ?? spec?.object ?? spec?.objectName;
+}
+var VIEW_OVERLAY_MARKER = "_isOverride";
+function isLegacyOverlayRow(item, spec) {
+  if (spec && spec.config && typeof spec.config === "object") return false;
+  const viewKind = item?.viewKind ?? spec?.viewKind;
+  return viewKind === "list";
+}
+function isPersonalizationOverlayRow(item, spec) {
+  if (item?.[VIEW_OVERLAY_MARKER] === true) return true;
+  if (spec?.[VIEW_OVERLAY_MARKER] === true) return true;
+  return isLegacyOverlayRow(item, spec);
+}
+var VIEW_OVERLAY_OWNED_KEYS = Object.freeze([
+  "rowHeight",
+  "sort",
+  "hiddenFields",
+  "columnState",
+  "inlineEdit"
+]);
+var VIEW_OVERLAY_IDENTITY_KEYS = Object.freeze([
+  "name",
+  "object",
+  "viewKind",
+  VIEW_OVERLAY_MARKER
+]);
+function narrowPersonalizationOverlay(row) {
+  if (!row || typeof row !== "object" || Array.isArray(row)) return row;
+  const item = row;
+  const spec = item.list ?? item;
+  if (!isPersonalizationOverlayRow(item, spec)) return row;
+  const narrowed = {};
+  for (const key of VIEW_OVERLAY_IDENTITY_KEYS) {
+    if (item[key] !== void 0) narrowed[key] = item[key];
+  }
+  for (const key of VIEW_OVERLAY_OWNED_KEYS) {
+    if (item[key] !== void 0) narrowed[key] = item[key];
+  }
+  return narrowed;
+}
+function unwrapViewDraft(resp) {
+  if (!resp || typeof resp !== "object") return null;
+  const env = resp;
+  const body = "item" in env ? env.item : env;
+  if (!body || typeof body !== "object") return null;
+  const 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 +1771,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 +1933,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 +2161,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 +2329,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 +2875,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 +3135,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}).
    *
-   * Result is cached identically to {@link getView}; saving a view via
-   * {@link updateViewConfig} invalidates the cache.
+   * 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}, 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.
@@ -3136,34 +3263,65 @@ var ObjectStackAdapter = class {
     }
   }
   /**
-   * Persist a view definition for an object.
+   * Persist a toolbar-driven view config patch — density, column widths,
+   * sort, hidden columns, inline edit. Symmetric counterpart to
+   * {@link getView}: writes the row to the server metadata store via
+   * `client.meta.saveItem`, then invalidates the matching cache entry so the
+   * next {@link getView} reflects the new payload. Returns the persisted item
+   * when the server echoes it, otherwise undefined.
+   *
+   * Called from exactly ONE production site — `ObjectView`'s
+   * `persistViewPatch`, for the toolbar toggle — but that ONE call site
+   * fires for BOTH kinds of active tab: a code-defined **system** view (no
+   * row of its own yet) and a genuinely user-created **saved** view (already
+   * has a row — the toggle is editing ITS OWN definition, not laying an
+   * overlay on top of it). Which one a given call means is NOT re-derived
+   * here from the write's shape (objectui#4227's own lesson: shape inference
+   * on this namespace is exactly what let a system view masquerade as
+   * saved) — the caller already knows, via the same `isSavedViewId`
+   * classification that gates the switcher's readonly flag and its five
+   * mutating handlers, and passes it as {@link opts.isSavedView}.
    *
-   * Symmetric counterpart to {@link getView}: writes the view to the
-   * server metadata store via `client.meta.saveItem`, then invalidates
-   * the matching cache entry so the next {@link getView} reflects the
-   * new payload. Returns the persisted item when the server echoes it,
-   * otherwise undefined.
+   * - `isSavedView` false/omitted (system-view target, the common case and
+   *   the default for backward compatibility): stamps
+   *   {@link VIEW_OVERLAY_MARKER} so {@link listViews} excludes the row —
+   *   the original objectui#4227 fix.
+   * - `isSavedView` true: the marker is withheld. Stamping it here would
+   *   flag the saved view's OWN row as a personalization overlay, and
+   *   `listViews()` would exclude it on the very next read — the user's own
+   *   view would vanish from the switcher the moment they toggled its
+   *   density (objectui#4227 follow-up, PM review on PR #4713, measured:
+   *   `persistViewPatch` has no gate on which kind of tab is active, and
+   *   this method writes to the exact same `(type='view', name=viewId)` key
+   *   {@link createView}/the ADR-0034 `viewEnvelope` seam already used for
+   *   that view, so the write is an upsert onto the saved view's row, not a
+   *   new one).
    *
-   * Used by ObjectView for "live" toolbar persistence (density,
-   * column widths, sort, etc.) and by the View Config Panel for
-   * explicit saves.
+   * Per objectstack#7494's ruling, the overlay this writes (system-view
+   * case) is ORG-WIDE shared view settings, not a per-user preference — a
+   * true per-user scope is a parked v18 direction on the platform side.
    *
    * @param objectName - Object name (e.g. 'lead')
    * @param viewId - View identifier (e.g. 'all_leads')
    * @param config - Full view definition to persist
+   * @param opts.isSavedView - Whether `viewId` already names a saved view
+   *   (vs. a system view being personalized for the first time). Omit /
+   *   `false` for the default overlay-marking behavior.
    */
-  async updateViewConfig(objectName, viewId, config) {
+  async updateViewConfig(objectName, viewId, config, opts) {
     await this.connect();
-    const merged = { ...config || {}, object: config?.object || objectName, name: viewId };
+    const merged = {
+      ...config || {},
+      object: config?.object || objectName,
+      name: viewId,
+      ...opts?.isSavedView ? {} : { [VIEW_OVERLAY_MARKER]: true }
+    };
     const result = await this.client.meta.saveItem(
       "view",
       viewId,
       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 +3332,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,10 +3352,11 @@ 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));
+        if (viewKind && FORM_FAMILY.has(viewKind)) return false;
+        if (isPersonalizationOverlayRow(v, spec)) return false;
+        return true;
       }).map((v) => {
         const spec = v.list ?? v;
         const isDraft = v._draft === true || spec?._draft === true;
@@ -3254,6 +3415,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 +3438,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.
@@ -3330,7 +3631,7 @@ var ObjectStackAdapter = class {
     try {
       const cacheKey = `app:${appId}`;
       return await this.metadataCache.get(cacheKey, async () => {
-        const result = await this.client.meta.getItem("apps", appId);
+        const result = await this.client.meta.getItem("app", appId);
         if (result && result.item) return result.item;
         return result ?? null;
       });
@@ -3338,6 +3639,56 @@ 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).
+   *
+   * The app LIST is the generic metadata list route `GET /api/v1/meta/:type`,
+   * requested with the singular type segment `app` — the same address this
+   * method appends a name to below, and the one `MetadataProvider` reads its
+   * items from. The server filters that list per session in `filterAppForUser`
+   * (`packages/rest/src/rest-server.ts`, applied inside the `:type` list handler
+   * once the type segment resolves to `app`), so an app withheld by
+   * `requiredPermissions` and an app
+   * that does not exist are byte-identical there: both are simply absent. A
+   * console reading only that list has one fact and two conditions, and it
+   * renders its copy for the wrong one — "it may still be publishing" over a
+   * 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.
@@ -3348,7 +3699,7 @@ var ObjectStackAdapter = class {
     try {
       const cacheKey = `page:${pageId}`;
       return await this.metadataCache.get(cacheKey, async () => {
-        const result = await this.client.meta.getItem("pages", pageId);
+        const result = await this.client.meta.getItem("page", pageId);
         if (result && result.item) return result.item;
         return result ?? null;
       });
@@ -3438,6 +3789,15 @@ var ObjectStackAdapter = class {
       if (failure.kind === "rejected") {
         throw new AnalyticsQueryRejectedError(failure.message, failure.code);
       }
+      if (failure.kind === "unauthenticated") {
+        throw new AnalyticsUnauthenticatedError({
+          serverCode: failure.code,
+          serverMessage: failure.message
+        });
+      }
+      if (failure.kind === "cube-not-found") {
+        throw e;
+      }
       if (failure.kind === "not-installed") {
         this.warnAnalyticsCapabilityOnce(failure.message);
       }
@@ -3490,7 +3850,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();
@@ -3507,14 +3877,35 @@ var ObjectStackAdapter = class {
       body: JSON.stringify(requestBody)
     });
     if (!res.ok) {
-      let detail = "";
+      let errBody;
       try {
-        const errBody = await res.json();
-        detail = errBody?.message || errBody?.error || JSON.stringify(errBody);
+        errBody = await res.json();
       } catch {
       }
-      if (res.status === 501 || res.status === 404) {
-        throw new AnalyticsNotInstalledError("POST /analytics/dataset/query", detail || void 0);
+      const { code: serverCode, message: serverMessage } = readAnalyticsErrorEnvelope(errBody);
+      const detail = serverMessage || (errBody === void 0 ? "" : JSON.stringify(errBody));
+      const surface = "POST /analytics/dataset/query";
+      const requestedDatasetName = typeof dataset === "string" ? dataset : typeof dataset?.name === "string" ? String(dataset.name) : void 0;
+      if (errorCodeIsAnyOf({ code: serverCode }, ["NOT_IMPLEMENTED", "ROUTE_NOT_FOUND"])) {
+        throw new AnalyticsNotInstalledError(surface, serverMessage, serverCode);
+      }
+      if (errorCodeIs({ code: serverCode }, "NOT_FOUND")) {
+        throw new AnalyticsDatasetNotFoundError({
+          datasetName: requestedDatasetName,
+          serverCode,
+          serverMessage
+        });
+      }
+      if (errorCodeIs({ code: serverCode }, "UNAUTHENTICATED")) {
+        throw new AnalyticsUnauthenticatedError({ serverCode, serverMessage });
+      }
+      if (serverCode === void 0) {
+        if (ANALYTICS_ABSENT_STATUSES.includes(res.status)) {
+          throw new AnalyticsNotInstalledError(surface, detail || void 0);
+        }
+        if (res.status === 401) {
+          throw new AnalyticsUnauthenticatedError({ serverMessage });
+        }
       }
       throw new Error(`Dataset query failed: ${res.status} ${res.statusText}${detail ? ` \u2014 ${detail}` : ""}`);
     }
@@ -3525,8 +3916,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,40 +4163,44 @@ function createObjectStackAdapter(config) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  API_ACCESS_DENIED_CODES,
+  APP_PERMISSION_DENIED_CODE,
+  AnalyticsDatasetNotFoundError,
   AnalyticsNotInstalledError,
   AnalyticsQueryRejectedError,
+  AnalyticsUnauthenticatedError,
   AuthenticationError,
   BulkOperationError,
-  CloudOperations,
   ConcurrentUpdateError,
   ConnectionError,
   DataApiValidationError,
   FILTER_OPERATOR_ALIASES,
-  IntegrationManager,
   MalformedFilterError,
   MetadataClient,
   MetadataNotFoundError,
   ObjectStackAdapter,
   ObjectStackError,
-  SecurityManager,
-  calculateAutoLayout,
+  VIEW_OVERLAY_OWNED_KEYS,
   classifyAnalyticsFailure,
   clearSharedDiscoveryCache,
-  createDefaultCanvasConfig,
   createErrorFromResponse,
   createObjectStackAdapter,
   createObjectStackUserStateAdapter,
-  generateContractManifest,
+  createQuietHttpLogger,
+  formatHttpFailureMessage,
   getSharedDiscovery,
   is404Error,
   isAnalyticsNotInstalledError,
+  isApiAccessDeniedError,
+  isAppPermissionDeniedError,
   isConcurrentUpdateError,
   isErrorType,
   isMalformedFilterError,
   isObjectStackError,
+  narrowPersonalizationOverlay,
   normaliseClientError,
+  readSaveAdvisories,
   readTransactionalBatchCapability,
   serializeOrderBy,
-  snapToGrid,
-  validatePluginContract
+  viewItemObjectName
 });