@object-ui/data-objectstack 17.3.0 → 17.5.0

package/src/index.ts

@@ -8,8 +8,23 @@
 
 import { ObjectStackClient, type QueryOptions as ObjectStackQueryOptions } from '@objectstack/client';
 import type { DroppedFieldsEvent } from '@objectstack/spec/data';
+// #4237 — the metadata save door's advisory reader, shared with `MetadataClient`
+// rather than forked. ONE reader, two call sites: the other client class calls it
+// from `MetadataClient.save` (#4133/#4236), this one from the interceptor below.
+import {
+  readSaveAdvisories,
+  type MetadataSaveAdvisoryEvent,
+  type MetadataSaveAdvisoryListener,
+} from './metadata-client';
+import type { AnalyticsResult, DatasetSelection } from '@objectstack/spec/contracts';
 import type {
   DataSource,
+  // #4564 — the canonical `deleteView` receipt shapes, declared beside the
+  // `DataSource` interface they belong to. Imported for the local uses below
+  // and re-exported under the same names further down, so this package's
+  // existing importers are untouched by the move.
+  DeleteViewResult,
+  ViewHomeDeleteOutcome,
   BatchTransactionOperation,
   DataSourceMutationEvent,
   QueryParams,
@@ -27,11 +42,12 @@ import type {
   ImportJobUndoResult,
   ListImportJobsOptions,
 } from '@object-ui/types';
-import { errorCodeIsAnyOf } from '@object-ui/types';
+import { errorCodeIs, errorCodeIsAnyOf } from '@object-ui/types';
 import {
   convertFiltersToAST,
   emulateBatchTransaction,
   normalizeSchemaReferenceKeys,
+  type DatasetDrillRange,
 } from '@object-ui/core';
 import { MetadataCache } from './cache/MetadataCache';
 import { MetadataClient } from './metadata-client';
@@ -439,6 +455,95 @@ export function is404Error(error: unknown): boolean {
   return errorCodeIsAnyOf({ code }, ['OBJECT_NOT_FOUND', 'RECORD_NOT_FOUND']);
 }
 
+/**
+ * The two denials the server derives from an object's `enable` block —
+ * `apiAccessDenialFromEnable` (objectstack `packages/rest/src/rest-server.ts`).
+ *
+ *   - `OBJECT_API_DISABLED` (404) — `enable.apiEnabled: false`; the object is
+ *     not exposed over the data API at all.
+ *   - `OBJECT_API_METHOD_NOT_ALLOWED` (405) — the operation is absent from the
+ *     `enable.apiMethods` whitelist.
+ *
+ * Both are **pure functions of the object's metadata**: no user, no permission,
+ * no context, no request body. So neither is transient and neither is
+ * per-user — when one happens it is a permanent property of that object, and
+ * every retry of every persona gets the identical answer.
+ *
+ * That is exactly why they must not be degraded into "no data". A 404 from a
+ * missing collection means *this backend doesn't have that table*, which the
+ * optional-collection probes below legitimately read as "feature unavailable";
+ * a 404 from `OBJECT_API_DISABLED` means *this page can never work*. Answering
+ * the second with an empty result set renders "you have no records" over a
+ * surface that is not allowed to have any (objectui#4408 — it also hid the
+ * upstream defect objectstack#7544 for its entire life, because a merely
+ * unpopulated page invites nobody to click through).
+ */
+export const API_ACCESS_DENIED_CODES = [
+  'OBJECT_API_DISABLED',
+  'OBJECT_API_METHOD_NOT_ALLOWED',
+] as const;
+
+/**
+ * True when `error` is an `enable`-block API denial (see
+ * {@link API_ACCESS_DENIED_CODES}).
+ *
+ * Discriminates on the ADR-0112 `code`, never on the status: 404 alone cannot
+ * separate a disabled object from a missing collection, and 405 alone cannot
+ * separate a withheld method from any other method rejection. The code survives
+ * the transport — `@objectstack/client`'s fetch wrapper stamps `error.code`
+ * from the response envelope, and both spellings are declared members of the
+ * spec's `StandardErrorCode` — so no heuristic on status is needed or wanted.
+ */
+export function isApiAccessDeniedError(error: unknown): boolean {
+  return errorCodeIsAnyOf(error, API_ACCESS_DENIED_CODES);
+}
+
+/**
+ * What the by-name meta app route said about THIS session's access to an app
+ * (objectui#4252 / objectstack#8013).
+ *
+ *  - `granted` — the route served the app document.
+ *  - `denied`  — the app EXISTS and the session lacks its `requiredPermissions`.
+ *    The only verdict a caller may render as an authorization refusal.
+ *  - `unknown` — anything else: an absent app, an unpublished one, an app
+ *    withheld by an absent optional service, an unreachable server, an adapter
+ *    that cannot ask. All of these are cases where the server declined to say
+ *    that a permission of the caller's is missing, so no caller may claim it.
+ *
+ * Three values rather than a boolean because the third is not a shade of the
+ * other two: "the app is missing" and "I could not find out" both have to leave
+ * the caller's existing copy alone, and collapsing them into `false` invites a
+ * consumer to read a failed probe as a positive absence.
+ */
+export type AppAccessVerdict = 'granted' | 'denied' | 'unknown';
+
+/**
+ * The ADR-0112 standard catalog code the by-name meta app route answers with
+ * when an app exists and the session lacks its `requiredPermissions`
+ * (objectstack#8013, `sendError(res, 403, 'PERMISSION_DENIED', …)` in
+ * `packages/rest/src/rest-server.ts`).
+ *
+ * Deliberately NOT a member of {@link API_ACCESS_DENIED_CODES}: those two are
+ * pure functions of an object's `enable` metadata — permanent, identical for
+ * every persona — whereas this one is a statement about the CALLER, and the same
+ * request by a different session succeeds. Same word "denied", different
+ * question, so a consumer that wants one must never match the other.
+ */
+export const APP_PERMISSION_DENIED_CODE = 'PERMISSION_DENIED';
+
+/**
+ * True when `error` is the by-name app route's permission denial.
+ *
+ * Discriminates on the ADR-0112 `code`, never on the status (objectui#4408): the
+ * route answers 403 for this and 404 for absence today, but a status is a
+ * transport fact many conditions share, while the code is the contract. The
+ * console's whole reason to call this is to tell two REFUSALS apart, and both
+ * are errors.
+ */
+export function isAppPermissionDeniedError(error: unknown): boolean {
+  return errorCodeIs(error, APP_PERMISSION_DENIED_CODE);
+}
+
 /**
  * Thrown when the deployment has no analytics capability installed
  * (framework#3891 / #4019).
@@ -640,17 +745,78 @@ export function normaliseClientError(error: unknown): unknown {
 }
 
 /**
- * Build a Logger compatible with @objectstack/client that demotes expected
- * 404 noise to console.debug. The client logs every non-2xx response with
- * `logger.error("HTTP request failed", undefined, { status, error })`, but
- * 404s on optional collections (sys_presence, sys_activity, …) are part of
+ * Fold an @objectstack/client HTTP-failure `meta` bag into the log MESSAGE.
+ *
+ * The client already hands us everything worth knowing —
+ * `logger.error("HTTP request failed", undefined, { method, url, status, error })`
+ * — but it hands it as the THIRD argument. Everything that flattens a console
+ * record to text (a headless/CDP console capture, a log shipper, a copied
+ * DevTools line) keeps only the message and renders the rest as `[object
+ * Object]` / `Object`, so a wall of failures carried no method, no URL and no
+ * status: the reporter of objectui#4042 had to diff the network panel by hand
+ * to find out that 30 red lines were all one benign pre-login burst.
+ *
+ * So the identifying fields go into the string itself, and the structured bag
+ * is STILL passed alongside for DevTools to expand — text for the flatteners,
+ * object for the inspectors, neither at the other's expense.
+ *
+ * Exported for tests. Returns `null` when `meta` carries none of the three
+ * fields, so callers keep the original message rather than printing a husk.
+ */
+export function formatHttpFailureMessage(
+  message: string,
+  meta?: Record<string, any>,
+): string | null {
+  if (!meta || typeof meta !== 'object') return null;
+  const method = typeof meta.method === 'string' && meta.method ? meta.method : undefined;
+  const url = typeof meta.url === 'string' && meta.url ? meta.url : undefined;
+  const status =
+    typeof meta.status === 'number'
+      ? meta.status
+      : typeof meta.statusCode === 'number'
+        ? meta.statusCode
+        : undefined;
+  if (!method && !url && status === undefined) return null;
+
+  // `code` is the ADR-0112 semantic error code. The client puts the parsed
+  // body under `meta.error`; some call sites hoist the code to the top level.
+  const errBody = meta.error && typeof meta.error === 'object' ? meta.error : undefined;
+  const rawCode =
+    (typeof meta.code === 'string' && meta.code) ||
+    (errBody && typeof (errBody as Record<string, unknown>).code === 'string'
+      ? ((errBody as Record<string, string>).code)
+      : undefined);
+
+  const parts = [method ?? 'GET', url ?? '<unknown url>'];
+  parts.push(`-> ${status ?? 'no status'}`);
+  if (rawCode) parts.push(`[${rawCode}]`);
+  return `${message}: ${parts.join(' ')}`;
+}
+
+/**
+ * Build a Logger compatible with @objectstack/client that (a) spells every
+ * request failure out in the message — see {@link formatHttpFailureMessage} —
+ * and (b) demotes expected 404 noise to console.debug. The client logs every
+ * non-2xx response with
+ * `logger.error("HTTP request failed", undefined, { method, url, status, error })`,
+ * but 404s on optional collections (sys_presence, sys_activity, …) are part of
  * normal degraded operation when those plugins aren't installed on the
  * server — they should not surface as errors in the browser DevTools.
  *
+ * NOTE the asymmetry, and keep it: 404-on-an-optional-collection is demoted
+ * because it is an EXPECTED outcome of a request we still mean to make. No
+ * other status is demoted — a 401 that survives the console's session gate
+ * (objectui#4042: a mid-session expiry, say) is a real event and must stay a
+ * visible, fully-identified error. The cure for doomed requests is not issuing
+ * them, never hiding them once issued.
+ *
  * Returned object is loosely typed because the spec's Logger interface lives
  * in a transitive package; using `any` keeps us decoupled.
+ *
+ * Exported so the console's log contract is testable, and so an app wiring its
+ * own `ObjectStackClient` gets the same identified failures.
  */
-function createQuietHttpLogger(): any {
+export function createQuietHttpLogger(): any {
   const isExpected404 = (meta?: Record<string, any>): boolean => {
     if (!meta || typeof meta !== 'object') return false;
     if (meta.status === 404 || meta.statusCode === 404) return true;
@@ -670,13 +836,16 @@ function createQuietHttpLogger(): any {
       console.warn(message, meta ?? ''),
     error: (message: string, error?: Error, meta?: Record<string, any>) => {
       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: string, error?: Error, meta?: Record<string, any>) =>
-      console.error(message, error ?? '', meta ?? ''),
+      console.error(formatHttpFailureMessage(message, meta) ?? message, error ?? '', meta ?? ''),
     log: (message: string, ...args: any[]) => console.log(message, ...args),
     child: () => logger,
     withTrace: () => logger,
@@ -830,6 +999,132 @@ function withoutNoOpDrops(
   return out;
 }
 
+/**
+ * Resolve which object a `type='view'` metadata item belongs to.
+ *
+ * The metadata index is name-only, not field-typed: `GET /api/v1/meta/view`
+ * accepts `?package=` and `?preview=draft` and nothing else (measured on
+ * framework `packages/rest/src/rest-server.ts` — the `GET /meta/:type`
+ * handler — and on `client.meta.getItems(type, { packageId })`). So every
+ * reader of the view namespace enumerates `type='view'` once and narrows to
+ * one object HERE, client-side.
+ *
+ * ONE spelling, one place, deliberately: {@link ObjectStackAdapter.listViews}
+ * and {@link ObjectStackAdapter.listViewOverrides} read the same rows out of
+ * the same namespace, and two private copies of "which object is this?" is a
+ * drift waiting to happen — the switcher showing a view whose override the
+ * grid cannot find, or the reverse.
+ *
+ * `object` is the identity field the write path stamps (and that the
+ * framework's overlay heals onto identity-less personalization rows —
+ * objectstack#2555); `data.object` is the config's data-provider target and
+ * `objectName` the legacy artifact spelling.
+ *
+ * **Exported** since objectui#4373, for the same one-spelling reason: a writer
+ * outside this module that holds a view BODY but not its object name (app-shell's
+ * `MetadataService`) needs the object to name the keys
+ * {@link ObjectStackAdapter.invalidateViewKeys} drops, and a fourth private copy
+ * of "which object is this?" is exactly the drift this accessor exists to
+ * prevent. Identity only — it names no cache key.
+ */
+export function viewItemObjectName(item: any): string | undefined {
+  // Handle both bare view spec and `{list: {...}}` artifact wrapper
+  const spec = item?.list ?? item;
+  return spec?.data?.object ?? spec?.object ?? spec?.objectName;
+}
+
+/**
+ * Unwrap a `?state=draft` view read into its bare body, or `null` when there
+ * is nothing pending (#4139).
+ *
+ * The framework answers EVERY single-item read — draft or published — in a
+ * `{type, name, item}` envelope. `MetadataClient.get()` unwraps it at the
+ * client boundary (objectui#4271) while `getDraft()` deliberately hands the
+ * envelope back, so this helper stays tolerant of both: the call below reaches
+ * it through `get()` and therefore already holds the body, and the passthrough
+ * limb keeps it correct for an envelope arriving by any other route. An empty
+ * body is normalized to `null` so the caller's "is this view draft-backed?"
+ * test is a plain truthiness check. Mirrors app-shell's `unwrapDraftBody`
+ * (ADR-0034 seam); the two live apart because the seam sits above this
+ * adapter, not beside it.
+ */
+function unwrapViewDraft(resp: unknown): Record<string, any> | null {
+  if (!resp || typeof resp !== 'object') return null;
+  const env = resp as Record<string, any>;
+  const body = 'item' in env ? env.item : env;
+  if (!body || typeof body !== 'object') return null;
+  // Same `{list: {...}}` artifact wrapper the published read unwraps.
+  const spec = body.list ?? body;
+  if (!spec || typeof spec !== 'object') return null;
+  return Object.keys(spec).length > 0 ? (spec as Record<string, any>) : null;
+}
+
+/**
+ * `deleteView`'s receipt shapes, RE-EXPORTED from `@object-ui/types` (#4564).
+ *
+ * #4479 first declared both here, because this adapter is where the widened
+ * receipt is produced. That left the shared `DataSource.deleteView?` unable to
+ * describe it: the dependency runs this package -> `@object-ui/types` and never
+ * the other way, so the interface kept the narrow `{ deleted: boolean }` and a
+ * consumer reaching this adapter THROUGH `DataSource` was handed a type with
+ * the per-home outcomes already discarded. Nothing failed to compile — a wider
+ * return is assignable to a narrower declaration — which is precisely why the
+ * gap was silent until #4564 measured it.
+ *
+ * So the canonical declarations now live beside the interface they belong to,
+ * in `packages/types/src/data.ts`, and this package re-exports them under the
+ * SAME names: every importer PR #4562 left pointing at
+ * `@object-ui/data-objectstack` keeps compiling, and now gets the very type the
+ * shared contract speaks rather than a structural twin of it. Pinned by
+ * `deleteViewContract.types.test.ts`, which asserts type IDENTITY — mutual
+ * assignability would have been satisfied by a copy that was already drifting.
+ */
+export type { DeleteViewResult, ViewHomeDeleteOutcome } from '@object-ui/types';
+
+/**
+ * Read one delete receipt into a {@link ViewHomeDeleteOutcome}.
+ *
+ * The `deleted ?? reset ?? true` ladder is carried over verbatim from the
+ * single-call `deleteView` this replaced, so a server that answers a shape
+ * with neither key is read exactly as it was before (#4479): the framework
+ * sends `reset`, the SDK's typed metadata shape names `deleted`, and the
+ * final `true` is the "it answered 2xx and said nothing" default.
+ */
+function readViewDeleteReceipt(result: unknown): ViewHomeDeleteOutcome {
+  const r = (result ?? undefined) as Record<string, any> | undefined;
+  return {
+    removed: !!(r?.deleted ?? r?.reset ?? true),
+    ...(typeof r?.reset === 'boolean' ? { reset: r.reset } : {}),
+    ...(typeof r?.message === 'string' ? { message: r.message } : {}),
+  };
+}
+
+/**
+ * Merge a partial view patch onto the CURRENT view document.
+ *
+ * ADR-0005 overlay rows store the *full* view document, so a partial update is
+ * a read-merge-write cycle and the merge must start from real current state —
+ * merging onto `{}` yields a `{label, name, object}` fragment the server
+ * rejects (422), which is exactly how a rename used to be lost (#4139).
+ *
+ * `name` is forced to the URL segment so the row key and `body.name` agree
+ * (#2767 P1), and `object` falls back through the two spellings a stored view
+ * may carry before defaulting to the caller's object.
+ */
+function mergeViewPatch(
+  current: Record<string, any>,
+  partial: Record<string, any>,
+  viewName: string,
+  objectName: string,
+): Record<string, any> {
+  return {
+    ...current,
+    ...partial,
+    name: viewName,
+    object: current?.object || current?.data?.object || objectName,
+  };
+}
+
 /**
  * ObjectStack Data Source Adapter
  *
@@ -912,6 +1207,13 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
   // shell can surface a toast instead of the strip passing silently.
   private writeWarningListeners = new Set<WriteWarningListener>();
 
+  // 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.
+  private saveAdvisoryListeners = new Set<MetadataSaveAdvisoryListener>();
+
   constructor(config: {
     baseUrl: string;
     token?: string;
@@ -929,6 +1231,9 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     // debug() so they don't pollute the browser console. Other log levels are
     // forwarded to the standard console.
     this.client = new ObjectStackClient({ ...config, logger: createQuietHttpLogger() });
+    // #4237 — one emitter for every metadata save this adapter's client makes,
+    // installed the moment the client exists so no save can precede it.
+    this.installSaveAdvisoryInterceptor();
     this.metadataCache = new MetadataCache(config.cache);
     this.autoReconnect = config.autoReconnect ?? true;
     this.maxReconnectAttempts = config.maxReconnectAttempts ?? 3;
@@ -1144,7 +1449,14 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         const result: unknown = await this.client.data.find<T>(resource, queryOptions);
         return this.normalizeQueryResult(result, params);
       } catch (err) {
-        if (is404Error(err)) {
+        // An `enable`-block denial is NOT a missing collection. The object
+        // exists and the server is deliberately refusing to expose it, forever
+        // and for everyone — degrading that to an empty result set tells the
+        // user "you have no records" about a page that can never hold any
+        // (objectui#4408). Rethrow so the surface can say what happened; the
+        // `missingResources` memo must not absorb it either, or the very first
+        // denial would silently pin every later call to empty.
+        if (!isApiAccessDeniedError(err) && is404Error(err)) {
           // Mark the resource so subsequent calls don't repeat the 404.
           this.missingResources.add(resource);
           return { data: [], total: 0 } as QueryResult<T>;
@@ -1444,6 +1756,122 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     };
   }
 
+  /**
+   * 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: MetadataSaveAdvisoryListener): () => void {
+    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.
+   */
+  private emitSaveAdvisory(event: MetadataSaveAdvisoryEvent): void {
+    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.
+   */
+  private installSaveAdvisoryInterceptor(): void {
+    const meta = this.client.meta;
+    const original = meta.saveItem.bind(meta);
+    meta.saveItem = async (type: string, name: string, item: any) => {
+      const result = await original(type, name, item);
+      // Everything below is best-effort by construction: the row is already
+      // committed server-side, so nothing the advisory channel does may change
+      // what this call returns or whether it throws.
+      try {
+        const advisories = readSaveAdvisories(result);
+        if (advisories.length > 0) {
+          this.emitSaveAdvisory({
+            type,
+            name,
+            mode: (result as { state?: string } | null | undefined)?.state === 'draft' ? 'draft' : 'publish',
+            advisories,
+          });
+        }
+      } catch (err) {
+        /* an advisory must never turn a committed save into a thrown error */
+        console.warn('ObjectStackAdapter: save-advisory read error', err);
+      }
+      return result;
+    };
+  }
+
   async create(resource: string, data: Partial<T>): Promise<T> {
     await this.connect();
     try {
@@ -1518,10 +1946,21 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         String(id),
         opts?.ifMatch ? { ifMatch: opts.ifMatch } : undefined,
       );
-      if (result.deleted) {
+      // `success`, not `deleted` (objectstack#5638). `DeleteDataResult.deleted`
+      // was a key no schema ever declared and no server path ever returned on
+      // `DELETE /data/:object/:id` — the client's interface was a wrong CLAIM
+      // about the response body, and `@objectstack/client` 17.0.0-rc.5
+      // corrected it to the schema's `success`.
+      //
+      // This was live here, not cosmetic: `result.deleted` compiled and read
+      // `undefined` at runtime, so the guard below never fired — a successful
+      // delete emitted NO mutation event, leaving every subscriber's cache
+      // stale — and this method, declared `Promise<boolean>`, actually resolved
+      // `undefined`. Following the rename is what restores both.
+      if (result.success) {
         this.emitMutation({ type: 'delete', resource, id });
       }
-      return result.deleted;
+      return result.success;
     } catch (err) {
       throw normaliseClientError(err);
     }
@@ -2230,6 +2669,16 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
       const errorBody = await res.json().catch(() => ({ message: res.statusText }));
       const err = new Error(errorBody?.error?.message || errorBody?.message || res.statusText) as any;
       err.status = res.status;
+      // Carry the ADR-0112 envelope, not just the status. This branch bypasses
+      // `@objectstack/client` — whose fetch wrapper stamps `code`/`httpStatus`
+      // from the error body — so dropping the code here made THIS path (the one
+      // taken whenever the view expands a lookup or runs a search) the only list
+      // fetch on which a semantic denial arrives indistinguishable from any
+      // other 404/405, leaving the surface nothing to discriminate on
+      // (objectui#4408). Same precedence as the client's wrapper: the top-level
+      // `code` first, then the nested envelope's.
+      err.code = errorBody?.code ?? errorBody?.error?.code;
+      err.httpStatus = res.status;
       throw err;
     }
 
@@ -2603,43 +3052,121 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     }
   }
 
+  /**
+   * **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: string, viewName: string): void {
+    // Ordered per-view key first, then the object's map — the order the pin
+    // suite records, so a reordering is a visible decision rather than drift.
+    this.metadataCache.invalidate?.(`view:${objectName}:${viewName}`);
+    this.metadataCache.invalidate?.(`view-overrides:${objectName}`);
+  }
+
   /**
    * Batch-fetch all persisted view overrides for an object.
    *
-   * Per-view runtime overrides (density, column widths, sort, …) are
-   * stored in the metadata registry under key `<objectName>/<viewName>`.
-   * Loading them per-view fires N HTTP GETs that return 404 for views
-   * the user has never customized — generates console noise on every
-   * page load. This batch method performs a single
-   * `GET /api/v1/meta/<objectName>` (returns `{type, items}`) and
-   * returns a `{viewName: override}` map. Returns an empty map if the
-   * server doesn't expose the listing or returns no items.
+   * Per-view runtime overrides (density, column widths, sort, hidden
+   * columns, inlineEdit …) live in the SAME metadata namespace the
+   * write path uses: `type='view'`, `name=<viewId>` (see
+   * {@link updateViewConfig}). Loading them per-view fires N HTTP GETs
+   * that 404 for every view the user never customized — console noise on
+   * every page load. This batch method performs a single
+   * `GET /api/v1/meta/view` (returns `{type, items}`) and narrows the
+   * result to `objectName` client-side, exactly as {@link listViews}
+   * does over the same rows (shared accessor: {@link viewItemObjectName}).
+   *
+   * objectui#3774 — this used to enumerate `GET /api/v1/meta/<objectName>`,
+   * putting the OBJECT name in the metadata TYPE slot. That key space is
+   * disjoint from the one the write path lands in, so the batch map came
+   * back empty for every object, forever, and every saved personalization
+   * read back as "setting didn't save".
+   *
+   * FAILURES REJECT — they are not answered as `{}`. An empty map is an
+   * authoritative "this object has no overrides" (callers may trust it and
+   * skip the per-view reads); a transport/permission failure is "I could
+   * not tell", and reporting the two as the same value is what made
+   * ObjectView's per-view {@link getView} fallback unreachable code. When
+   * we cannot tell, we do not pretend we can. Rejections are not cached
+   * (the cache stores on success only), so a transient failure does not
+   * pin an empty answer for the TTL.
    *
-   * Result is cached identically to {@link getView}; saving a view via
-   * {@link updateViewConfig} invalidates the cache.
+   * Result is cached identically to {@link getView}, and EVERY view write —
+   * on this adapter and above it — invalidates it through the one seam,
+   * {@link invalidateViewKeys}. For a long time only {@link updateViewConfig}
+   * did (objectui#4363), which left the other three adapter paths stale
+   * for the cache's 5-minute TTL. That gap does not self-heal: the consumer
+   * (`loadViewOverrides`, app-shell `ObjectView`) treats a RESOLVED map as
+   * authoritative and deliberately does not re-probe per view — objectui#3774,
+   * and correct, since re-probing reinstates the 404 flurry the batch read
+   * exists to remove. So a stale map here is served in full, and the per-view
+   * {@link getView} fallback that would have masked it never runs.
    *
    * @param objectName - Object name (e.g. 'lead')
    * @returns Map keyed by view name with the persisted override config
+   * @throws whatever the metadata transport throws — callers that have a
+   *   per-view fallback should catch and use it.
    */
   async listViewOverrides(objectName: string): Promise<Record<string, any>> {
     await this.connect();
 
-    try {
-      const cacheKey = `view-overrides:${objectName}`;
-      return await this.metadataCache.get(cacheKey, async () => {
-        const result: any = await this.client.meta.getItems(objectName);
-        const items: any[] = Array.isArray(result?.items) ? result.items : [];
-        const out: Record<string, any> = {};
-        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: any = await this.client.meta.getItems('view');
+      const items: any[] = Array.isArray(result?.items)
+        ? result.items
+        : Array.isArray(result) ? result : [];
+      const out: Record<string, any> = {};
+      for (const it of items) {
+        if (!it || typeof it !== 'object') continue;
+        if (viewItemObjectName(it) !== objectName) continue;
+        // Keyed by the item's canonical `name` — the SAME identity
+        // `updateViewConfig` writes under and `getView` reads back by, which
+        // is what makes this a drop-in substitute for the per-view fetch.
+        // No `?? id ?? _name` alias chain: those are not view identities on
+        // any route (`/meta/view/:name` is name-addressed), and a batch map
+        // keyed by something no caller can ask for is dead weight.
+        const key = it.name;
+        if (typeof key === 'string' && key) out[key] = it;
+      }
+      return out;
+    });
   }
 
   /**
@@ -2705,12 +3232,8 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
       viewId,
       merged
     );
-    // Invalidate cached read so next getView reflects the change
-    const cacheKey = `view:${objectName}:${viewId}`;
-    this.metadataCache.invalidate?.(cacheKey);
-    // Also invalidate the batch override map so listViewOverrides re-fetches
-    this.metadataCache.invalidate?.(`view-overrides:${objectName}`);
-    this.metadataCache.invalidate?.(`views:${objectName}`);
+    // One seam names the key set for every writer (objectui#4373).
+    this.invalidateViewKeys(objectName, viewId);
     if (result && result.item) return result.item;
     return result ?? undefined;
   }
@@ -2722,8 +3245,10 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
    * 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: string,
@@ -2762,8 +3287,7 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         if (!v) return false;
         // Handle both bare view spec and `{list: {...}}` artifact wrapper
         const spec = v.list ?? v;
-        const obj = spec?.data?.object ?? spec?.object ?? spec?.objectName;
-        if (obj !== objectName) return false;
+        if (viewItemObjectName(v) !== objectName) return false;
         const viewKind = v.viewKind ?? spec?.viewKind;
         return !(viewKind && FORM_FAMILY.has(viewKind));
       }).map((v: any) => {
@@ -2841,6 +3365,10 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
    *
    * 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: string,
@@ -2870,16 +3398,57 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
       data: spec?.data || { provider: 'object', object: objectName },
     };
     const result: any = await this.client.meta.saveItem('view', name, fullSpec);
-    this.metadataCache.invalidate?.(`views:${objectName}`);
+    // `saveItem` is an UPSERT: an explicit `spec.name` that already exists
+    // overwrites the published row, which a prior `getView` may hold. (A
+    // generated name cannot collide, and a miss is a `Map.delete` on an absent
+    // key, so the uniform rule costs nothing on the create-a-new-row path.)
+    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: string,
@@ -2887,42 +3456,159 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     partial: Record<string, any>,
   ): Promise<Record<string, any> | void> {
     await this.connect();
-    let current: any = {};
+
+    // ── Draft-addressed path ────────────────────────────────────────────
+    // `MetadataClient.get` answers `null` on 404 (no draft pending) and throws
+    // on anything else, so a transport failure here is NOT read as "published".
+    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;
+    }
+
+    // ── Published-overlay path (unchanged addressing) ────────────────────
+    let current: any;
     try {
       const r: any = await this.client.meta.getItem('view', viewName);
       current = (r && (r.item || r)) || {};
       // Some endpoints return the bare item; others wrap as {type,name,item}
       if (current?.list) current = current.list;
-    } catch {
-      // Treat missing as create-equivalent
+    } catch (err) {
+      if (is404Error(err)) {
+        // Not a draft, not published, not an artifact — there is nothing to
+        // merge onto. Fail loudly instead of emitting the partial write.
+        throw Object.assign(
+          new Error(
+            `updateView: view "${viewName}" not found on object "${objectName}"` +
+              ' — no pending draft and no published overlay. Use createView() to create one.',
+          ),
+          { cause: err },
+        );
+      }
+      // Network / permission / server fault: surface it. Degrading to a
+      // create-equivalent write here is what corrupted the row before.
+      throw err;
     }
-    const merged = {
-      ...current,
-      ...partial,
-      name: viewName,
-      object: current?.object || (current as any)?.data?.object || objectName,
-    };
+
+    const merged = mergeViewPatch(current, partial, viewName, objectName);
     const result: any = 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: string,
     viewName: string,
-  ): Promise<{ deleted: boolean }> {
+  ): Promise<DeleteViewResult> {
     await this.connect();
-    const result: any = 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 {
+      // ── Draft home, first ────────────────────────────────────────────────
+      const draft = readViewDeleteReceipt(
+        await metaClient.reset('view', viewName, { state: 'draft' }),
+      );
+
+      // ── Published home ───────────────────────────────────────────────────
+      let published: ViewHomeDeleteOutcome;
+      try {
+        published = readViewDeleteReceipt(await metaClient.reset('view', viewName));
+      } catch (err) {
+        const outcome: DeleteViewResult = {
+          deleted: false,
+          draft,
+          published: { removed: false },
+        };
+        throw Object.assign(
+          new Error(
+            `deleteView: view "${viewName}" on object "${objectName}" is NOT fully removed` +
+              ` — 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);
+    }
   }
 
 
@@ -2951,6 +3637,58 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     }
   }
 
+  /**
+   * Ask the by-name meta app route WHY an app is not in this session's app list
+   * (objectui#4252).
+   *
+   * `GET /api/v1/meta/apps` is filtered per session server-side
+   * (`filterAppForUser`), so an app withheld by `requiredPermissions` and an app
+   * that does not exist are byte-identical there: both are simply absent. A
+   * console reading only that list has one fact and two conditions, and it
+   * renders its copy for the wrong one — "it may still be publishing" over a
+   * permanent authorization decision, which cost a downstream acceptance round
+   * two test batches spent chasing a platform defect that was a missing
+   * permission-set binding.
+   *
+   * The maintainer ruling (2026-08-12) put the answer on the BY-NAME route
+   * rather than in the list, so the enumeration surface is not widened past what
+   * a by-name probe already implies (objectstack#8013 / PR #8135): an app that
+   * exists and whose `requiredPermissions` the session lacks answers `403` with
+   * `PERMISSION_DENIED` in the declared envelope, and absence — a nonexistent
+   * name, an unpublished app, an app gated by an absent optional service —
+   * keeps answering `404 RESOURCE_NOT_FOUND`.
+   *
+   * ## Why this is a separate method and not a flavour of {@link getApp}
+   *
+   *  - `getApp` degrades EVERY failure to `null`, which is exactly the
+   *    conflation this exists to undo; changing it would silently re-point its
+   *    own callers' fallback-to-static-config path.
+   *  - `getApp` memoises in `metadataCache`. A verdict about the CALLER must not
+   *    be cached beside a document about the APP — one grant, and a cached
+   *    denial outlives the session it described.
+   *
+   * Nothing here throws: a probe that cannot reach an answer returns `unknown`
+   * and the caller keeps whatever it was already showing. Only the measured
+   * `code` produces `denied` — never a status, never a message (objectui#4408).
+   *
+   * @param appName - the app name as it appears in the URL segment
+   */
+  async probeAppAccess(appName: string): Promise<AppAccessVerdict> {
+    if (!appName) return 'unknown';
+    try {
+      // Singular `app`, the address objectstack#8013 pinned its cases against,
+      // and the same one `MetadataProvider` reads items by. No `connect()`
+      // first: this route is only ever asked after the app LIST has already
+      // loaded through this same client, and the client's route resolution
+      // falls back to the conventional `/api/v1/meta` regardless — so a
+      // discovery round trip here could only add a failure mode.
+      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.
@@ -3179,36 +3917,70 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
    * 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: Record<string, unknown> | string,
-    selection: {
-      dimensions?: string[];
-      measures: string[];
-      runtimeFilter?: Record<string, unknown>;
-      timeDimensions?: unknown[];
-      compareTo?: { kind: 'previousPeriod' | 'previousYear'; dimension: string };
-      order?: Record<string, 'asc' | 'desc'>;
-      limit?: number;
-      offset?: number;
-      timezone?: string;
-      /** Marginal-aggregate groupings (e.g. `[rows, [colDim], []]`) — server
-       *  computes each subtotal with the measure's TRUE aggregate (never client
-       *  re-derived). `[]` is the grand total. */
-      totals?: { groupings: string[][] };
-    },
+    selection: DatasetSelection,
   ): Promise<{
     rows: Array<Record<string, unknown>>;
-    /** Column metadata: a display `label` (dimensions and measures), and a
-     *  measure's numeral `format` + declared `currency` for value formatting. */
-    fields: Array<{ name: string; type: string; label?: string; format?: string; currency?: string }>;
+    /**
+     * Column metadata — the spec's `AnalyticsResult.fields[]` element BY
+     * REFERENCE, never a local restatement of it (objectui#3752). Read
+     * `@objectstack/spec` for what a column carries; this comment deliberately
+     * does not re-list the keys, because the enumeration it replaced was the
+     * bug: it named five (`name`/`type`/`label`/`format`/`currency`) and stopped
+     * at the contract of the day it was written, so it never grew
+     * `percentScale` — the server's answer to whether a percentage column is a
+     * 0–1 fraction or already percentage points. The spec says a renderer that
+     * receives it "must scale by it instead of guessing from the value"
+     * (objectui#3136), so a declaration that hides the key steers a typed
+     * consumer into exactly the guess-by-magnitude the issue banned. Pinned in
+     * `queryDataset.test.ts`.
+     *
+     * Only this element is spec-owned: the envelope around it (`object` /
+     * `dimensionFields` / `drillRawRows`) is ADR-0021 D2 drill metadata the REST
+     * route adds on top of `AnalyticsResult`, and this method never returns the
+     * result's `sql`, so the whole envelope is NOT an `AnalyticsResult`.
+     */
+    fields: Array<AnalyticsResult['fields'][number]>;
     /** ADR-0021 D2 drill-through: the dataset's base object (records to drill into). */
     object?: string;
     /** Drillable dimension NAME → underlying object FIELD name. */
     dimensionFields?: Record<string, string>;
     /** Raw grouped values per row (aligned to `rows` by index) for drill filters. */
     drillRawRows?: Array<Record<string, unknown>>;
+    /**
+     * Half-open date-range drill scope per row (framework#1752), aligned to
+     * `rows` by index: dimension NAME → the field and `[gte, lt)` bounds of that
+     * row's time bucket. The RANGE companion to `drillRawRows`, which handles
+     * equality dims only — a `dateGranularity` dimension groups a SPAN of
+     * records into one bucket, so the server excludes date dims from
+     * `dimensionFields`/`drillRawRows` and sends this sidecar instead.
+     *
+     * The entry type is `@object-ui/core`'s `DatasetDrillRange` BY REFERENCE,
+     * not a local restatement of it (objectui#3613/#3752 discipline): the same
+     * declaration is what `buildDatasetDrillFilter` — the single consumer that
+     * turns these bounds into an ObjectQL `{ $gte, $lt }` — accepts, and what
+     * `DatasetWidget` / `DatasetReportRenderer` type their state with. Nothing
+     * in `@objectstack/spec` owns this shape yet (the server's own
+     * `AnalyticsResultWithDrill` is local to `service-analytics`), so the shared
+     * in-repo interface is the one contract available; restating it here would
+     * make a third dialect of it. Like `drillRawRows`, only the ARRAY is
+     * validated below — the bounds are unvalidated payload, which is exactly why
+     * `DatasetDrillRange` declares them `unknown`.
+     */
+    drillRanges?: Array<Record<string, DatasetDrillRange>>;
     /** Server-computed marginal aggregates, one entry per requested grouping. */
     totals?: Array<{ dimensions: string[]; rows: Array<Record<string, unknown>> }>;
   }> {
@@ -3275,8 +4047,16 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         ? ((data as any).dimensionFields as Record<string, string>)
         : undefined;
     const drillRawRows = Array.isArray((data as any)?.drillRawRows) ? (data as any).drillRawRows : undefined;
+    // framework#1752 — the date-range sidecar. Dropping it here (objectui#3813)
+    // made date-bucket drill-through impossible through the only real adapter:
+    // a widget grouped ONLY by a date dimension gets no `dimensionFields` (the
+    // server excludes date dims from the equality drill), so `drillRanges` is
+    // the ONLY thing that can make `canDrill` true — with the key hand-picked
+    // away, the whole drill entry point disappeared, and a mixed grouping
+    // drilled to a superset (every bucket, not the clicked one).
+    const drillRanges = Array.isArray((data as any)?.drillRanges) ? (data as any).drillRanges : undefined;
     const totals = Array.isArray((data as any)?.totals) ? (data as any).totals : undefined;
-    return { rows, fields, object, dimensionFields, drillRawRows, totals };
+    return { rows, fields, object, dimensionFields, drillRawRows, drillRanges, totals };
   }
 
   /** Client-side aggregation fallback */
@@ -3610,9 +4390,10 @@ export {
 export type { MetadataCacheStats } from './cache/MetadataCache';
 
 // v3.0.0 Deep Integration modules
-export { CloudOperations } from './cloud';
-export type { CloudDeploymentConfig, CloudHostingConfig, CloudMarketplaceEntry } from './cloud';
-
+// (The cloud deployment/hosting/marketplace surface that used to be re-exported
+// here was retired by objectui#4152 — it called into a client namespace that
+// does not exist and fabricated success. `cloud-surface-retired-4152.pin.test.ts`
+// fails if it returns; that file names the retired symbols, this one must not.)
 export { validatePluginContract, generateContractManifest } from './contracts';
 
 // User-scoped persistence adapter (favorites / recent items / …)
@@ -3630,8 +4411,11 @@ export type { IntegrationConfig, IntegrationTrigger, IntegrationProvider, SlackI
 // Used by plugin-designer to back the Setup-app Object Manager and Field
 // Designer surfaces; kept separate from ObjectStackAdapter so callers
 // can use it without the full data-source surface.
-export { MetadataClient } from './metadata-client';
+export { MetadataClient, readSaveAdvisories } from './metadata-client';
 export type {
+  RuntimeAuthoringIssue,
+  MetadataSaveAdvisoryEvent,
+  MetadataSaveAdvisoryListener,
   MetadataClientConfig,
   MetadataListOptions,
   MetadataDraftHeader,