@object-ui/data-objectstack 17.5.0 → 17.6.0

package/dist/index.js

@@ -246,7 +246,6 @@ var MetadataClient = class _MetadataClient {
       "Content-Type": "application/json"
     };
     if (options.ifMatch) headers["If-Match"] = options.ifMatch;
-    if (options.actor) headers["X-Actor"] = options.actor;
     const res = await this.fetchImpl(url, {
       method: "PUT",
       headers,
@@ -295,13 +294,39 @@ var MetadataClient = class _MetadataClient {
     return inner;
   }
   /**
-   * Get the 3-state layered view of a metadata item (Phase 3a). Returns
-   * `code` (the artifact / fallback default), `overlay` (the saved
-   * customisation, if any), and `effective` (what the runtime sees).
+   * Get the 3-state layered view of a metadata item: `code` (the packaged
+   * artifact baseline), `overlay` (the tenant customisation row alone) and
+   * `effective` (the merged value the runtime sees).
+   *
+   * Reads **`GET /meta/:type/:name/layers`** — the path the framework declares
+   * for this projection, with a response schema of its own
+   * (`GetMetaItemLayeredResponseSchema`, objectstack#5882 ruling B). It used to
+   * be reached by hanging a `layers` flag on the ordinary item read, which made
+   * one route answer two unrelated representations while `packages/spec`
+   * declared only one of them. That spelling still answers this same body
+   * inside its deprecation window (the response carries RFC 9745
+   * `Deprecation: true` and an RFC 8288 `Link: rel="successor-version"` back to
+   * this path) and is scheduled for removal upstream, so nothing here may
+   * depend on it — the repo-wide ratchet is
+   * `scripts/__tests__/layered-read-declared-path-4016.test.ts`.
+   *
+   * The request is built here rather than delegated to `@objectstack/client`
+   * because the SDK expresses no layered read in EITHER spelling: the
+   * framework's REST route ledger records this route as `server-only`,
+   * "consumed by objectui over plain HTTP", and whether the SDK should express
+   * it is an open upstream product call.
+   *
+   * One behaviour delta rides along with the path, and it is the server's
+   * choice rather than ours: the retired flag FELL THROUGH to the plain item
+   * read on a backend whose protocol implementation had no layered support,
+   * answering the `{ type, name, item }` envelope. A dedicated path refuses to
+   * answer a different resource under this one's declared shape, so it returns
+   * 501 `NOT_IMPLEMENTED` instead — which surfaces here as a thrown error
+   * rather than a view with `code` and `overlay` silently blank.
    */
   async layered(type, name, options = {}) {
-    const pkg = options.packageId ? `&package=${encodeURIComponent(options.packageId)}` : "";
-    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}?layers=true${pkg}`;
+    const qs = options.packageId ? `?package=${encodeURIComponent(options.packageId)}` : "";
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}/layers${qs}`;
     const res = await this.fetchImpl(url, { method: "GET", headers: this.headers, cache: "no-store" });
     if (res.status === 404) {
       return { code: null, overlay: null, overlayScope: null, effective: null };
@@ -391,7 +416,6 @@ var MetadataClient = class _MetadataClient {
     const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}${qs}`;
     const headers = { ...this.headers };
     if (options.ifMatch) headers["If-Match"] = options.ifMatch;
-    if (options.actor) headers["X-Actor"] = options.actor;
     const res = await this.fetchImpl(url, { method: "DELETE", headers });
     if (!res.ok) throw await parseError(res);
     return await res.json();
@@ -409,7 +433,6 @@ var MetadataClient = class _MetadataClient {
       ...this.headers,
       "Content-Type": "application/json"
     };
-    if (options.actor) headers["X-Actor"] = options.actor;
     const res = await this.fetchImpl(url, {
       method: "POST",
       headers,
@@ -432,7 +455,6 @@ var MetadataClient = class _MetadataClient {
       ...this.headers,
       "Content-Type": "application/json"
     };
-    if (options.actor) headers["X-Actor"] = options.actor;
     const res = await this.fetchImpl(url, {
       method: "POST",
       headers,
@@ -1037,52 +1059,6 @@ function isErrorType(error, errorClass) {
   return error instanceof errorClass;
 }
 
-// src/contracts.ts
-function validatePluginContract(contract) {
-  const errors = [];
-  const warnings = [];
-  if (!contract.name || contract.name.trim().length === 0) {
-    errors.push({ field: "name", message: "Plugin name is required", code: "MISSING_NAME" });
-  }
-  if (!contract.version || !/^\d+\.\d+\.\d+/.test(contract.version)) {
-    errors.push({ field: "version", message: "Valid semver version is required", code: "INVALID_VERSION" });
-  }
-  if (!contract.exports || contract.exports.length === 0) {
-    errors.push({ field: "exports", message: "At least one export is required", code: "NO_EXPORTS" });
-  }
-  if (contract.exports) {
-    const validTypes = ["component", "hook", "utility", "provider"];
-    for (const exp of contract.exports) {
-      if (!exp.name) {
-        errors.push({ field: "exports.name", message: "Export name is required", code: "MISSING_EXPORT_NAME" });
-      }
-      if (!validTypes.includes(exp.type)) {
-        errors.push({ field: "exports.type", message: `Invalid export type: ${exp.type}`, code: "INVALID_EXPORT_TYPE" });
-      }
-    }
-  }
-  if (!contract.permissions || contract.permissions.length === 0) {
-    warnings.push("No permissions declared \u2014 plugin will have minimal access");
-  }
-  return { valid: errors.length === 0, errors, warnings };
-}
-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) {
@@ -1185,267 +1161,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: "=",
@@ -1473,6 +1188,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",
@@ -1633,21 +1357,83 @@ 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 +1448,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 {
@@ -1741,8 +1536,14 @@ function createQuietHttpLogger() {
     return false;
   };
   const logger = {
-    debug: (message, meta) => console.debug(message, meta ?? ""),
-    info: (message, meta) => console.info(message, meta ?? ""),
+    debug: (message, meta) => (
+      // eslint-disable-next-line no-console -- objectui#4029, see comment above
+      console.debug(message, meta ?? "")
+    ),
+    info: (message, meta) => (
+      // eslint-disable-next-line no-console -- objectui#4029, see comment above
+      console.info(message, meta ?? "")
+    ),
     warn: (message, meta) => console.warn(message, meta ?? ""),
     error: (message, error, meta) => {
       if (isExpected404(meta)) {
@@ -1755,6 +1556,7 @@ function createQuietHttpLogger() {
       console.error(formatHttpFailureMessage(message, meta) ?? message, error ?? "", meta ?? "");
     },
     fatal: (message, error, meta) => console.error(formatHttpFailureMessage(message, meta) ?? message, error ?? "", meta ?? ""),
+    // eslint-disable-next-line no-console -- objectui#4029, see comment above
     log: (message, ...args) => console.log(message, ...args),
     child: () => logger,
     withTrace: () => logger
@@ -1797,6 +1599,44 @@ 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;
@@ -3366,25 +3206,59 @@ 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,
@@ -3423,7 +3297,9 @@ var ObjectStackAdapter = class {
         const spec = v.list ?? v;
         if (viewItemObjectName(v) !== objectName) return false;
         const viewKind = v.viewKind ?? spec?.viewKind;
-        return !(viewKind && FORM_FAMILY.has(viewKind));
+        if (viewKind && FORM_FAMILY.has(viewKind)) return false;
+        if (isPersonalizationOverlayRow(v, spec)) return false;
+        return true;
       }).map((v) => {
         const spec = v.list ?? v;
         const isDraft = v._draft === true || spec?._draft === true;
@@ -3698,7 +3574,7 @@ var ObjectStackAdapter = class {
     try {
       const cacheKey = `app:${appId}`;
       return await this.metadataCache.get(cacheKey, async () => {
-        const result = await this.client.meta.getItem("apps", appId);
+        const result = await this.client.meta.getItem("app", appId);
         if (result && result.item) return result.item;
         return result ?? null;
       });
@@ -3710,8 +3586,13 @@ var ObjectStackAdapter = class {
    * Ask the by-name meta app route WHY an app is not in this session's app list
    * (objectui#4252).
    *
-   * `GET /api/v1/meta/apps` is filtered per session server-side
-   * (`filterAppForUser`), so an app withheld by `requiredPermissions` and an app
+   * The app LIST is the generic metadata list route `GET /api/v1/meta/:type`,
+   * requested with the singular type segment `app` — the same address this
+   * method appends a name to below, and the one `MetadataProvider` reads its
+   * items from. The server filters that list per session in `filterAppForUser`
+   * (`packages/rest/src/rest-server.ts`, applied inside the `:type` list handler
+   * once the type segment resolves to `app`), so an app withheld by
+   * `requiredPermissions` and an app
    * that does not exist are byte-identical there: both are simply absent. A
    * console reading only that list has one fact and two conditions, and it
    * renders its copy for the wrong one — "it may still be publishing" over a
@@ -3761,7 +3642,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;
       });
@@ -3851,6 +3732,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);
       }
@@ -3930,14 +3820,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}` : ""}`);
     }
@@ -4196,31 +4107,29 @@ function createObjectStackAdapter(config) {
 export {
   API_ACCESS_DENIED_CODES,
   APP_PERMISSION_DENIED_CODE,
+  AnalyticsDatasetNotFoundError,
   AnalyticsNotInstalledError,
   AnalyticsQueryRejectedError,
+  AnalyticsUnauthenticatedError,
   AuthenticationError,
   BulkOperationError,
   ConcurrentUpdateError,
   ConnectionError,
   DataApiValidationError,
   FILTER_OPERATOR_ALIASES,
-  IntegrationManager,
   MalformedFilterError,
   MetadataClient,
   MetadataNotFoundError,
   ObjectStackAdapter,
   ObjectStackError,
-  SecurityManager,
-  calculateAutoLayout,
+  VIEW_OVERLAY_OWNED_KEYS,
   classifyAnalyticsFailure,
   clearSharedDiscoveryCache,
-  createDefaultCanvasConfig,
   createErrorFromResponse,
   createObjectStackAdapter,
   createObjectStackUserStateAdapter,
   createQuietHttpLogger,
   formatHttpFailureMessage,
-  generateContractManifest,
   getSharedDiscovery,
   is404Error,
   isAnalyticsNotInstalledError,
@@ -4230,11 +4139,10 @@ export {
   isErrorType,
   isMalformedFilterError,
   isObjectStackError,
+  narrowPersonalizationOverlay,
   normaliseClientError,
   readSaveAdvisories,
   readTransactionalBatchCapability,
   serializeOrderBy,
-  snapToGrid,
-  validatePluginContract,
   viewItemObjectName
 };