@object-ui/data-objectstack 17.2.0 → 17.5.0

package/src/metadata-client.ts

@@ -32,6 +32,84 @@
  * type, mirroring the framework's "single Zod source per type" rule.
  */
 
+import type { RuntimeAuthoringIssue } from '@objectstack/spec/api';
+
+/**
+ * One advisory finding the framework's runtime authoring gate produced for a
+ * save that SUCCEEDED (objectstack#7435, landed as `89d7b35a7`).
+ *
+ * Re-exported from `@objectstack/spec` rather than restated: this is the D3
+ * finding shape, declared once as `RuntimeAuthoringIssueSchema` and shared with
+ * the 422 `issues[]` so the two cannot drift apart. Hand-copying the six keys
+ * here is exactly the fork `check:spec-symbol-derivation` exists to reject, and
+ * it is the same discipline `DroppedFieldsEvent` already follows one module over.
+ *
+ * `severity` carries the spec's full `error | warning | info` union. On THIS
+ * channel it is never `'error'` — an error-severity finding is a 422 and never
+ * reaches a 2xx body — but the union is copied whole rather than narrowed,
+ * because a consumer-side re-spelling of a producer's enum is the drift the
+ * gate above is about.
+ */
+export type { RuntimeAuthoringIssue };
+
+/**
+ * Emitted after a {@link MetadataClient.save} whose response carried a
+ * non-empty `advisories` array. The save SUCCEEDED — the row persisted and the
+ * server returned 200 — so this is advisory, never a failure.
+ *
+ * Deliberately the same shape of seam as `ObjectStackAdapter.onWriteWarning`
+ * (#3431/#3455): a successful write whose response carries something the author
+ * needs to be told, surfaced to the shell as an event so the data layer never
+ * imports a toaster. The difference is only which door produced it — that one
+ * is record CRUD, this one is the metadata save door.
+ */
+export interface MetadataSaveAdvisoryEvent {
+  /** Metadata type saved (e.g. `'flow'`). */
+  type: string;
+  /** Item name saved. */
+  name: string;
+  /**
+   * The save mode the call used. `'draft'` writes are **never gated** — the
+   * framework returns at `runtime-authoring-gate.ts`'s D1 early-return
+   * (`if (args.state !== 'active') return null`), so a draft save produces no
+   * findings at all and this event never fires for one. Carried anyway so a
+   * consumer reading the event can tell which door it came through.
+   */
+  mode: 'draft' | 'publish';
+  /** The findings. Never empty — the event is not emitted otherwise. */
+  advisories: RuntimeAuthoringIssue[];
+}
+
+/** Event listener type for save-advisory events. */
+export type MetadataSaveAdvisoryListener = (event: MetadataSaveAdvisoryEvent) => void;
+
+/**
+ * Read the `advisories` array off a save response, defensively.
+ *
+ * The server omits the key entirely on a clean save, so `undefined` is the
+ * common case and means "nothing to say". Anything that is not an array of
+ * objects carrying the six required keys is dropped rather than rendered: a
+ * half-shaped finding would print blanks at the author, and this channel must
+ * never turn a successful save into noise.
+ */
+export function readSaveAdvisories(body: unknown): RuntimeAuthoringIssue[] {
+  if (!body || typeof body !== 'object') return [];
+  const raw = (body as { advisories?: unknown }).advisories;
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((f): f is RuntimeAuthoringIssue => {
+    if (!f || typeof f !== 'object') return false;
+    const c = f as Record<string, unknown>;
+    return (
+      typeof c.rule === 'string' &&
+      typeof c.path === 'string' &&
+      typeof c.where === 'string' &&
+      typeof c.message === 'string' &&
+      typeof c.hint === 'string' &&
+      typeof c.severity === 'string'
+    );
+  });
+}
+
 export interface MetadataClientConfig {
   /** Base URL of the ObjectStack server (no trailing slash needed). */
   baseUrl: string;
@@ -55,6 +133,22 @@ export interface MetadataClientConfig {
    * nothing the preview shows is live until Publish.
    */
   previewDrafts?: boolean;
+  /**
+   * Called after a {@link MetadataClient.save} whose 2xx response carried a
+   * non-empty `advisories` array (objectstack#7435). The save already
+   * succeeded; this is how the shell learns there is something to tell the
+   * author instead of the findings being discarded client-side.
+   *
+   * Set on the CONFIG rather than exposed as a `subscribe()` method on purpose:
+   * console metadata clients are minted per-component by `useMetadataClient`,
+   * so there is no long-lived instance to subscribe to — but every one of them
+   * is built by the single `createConsoleMetadataClient` factory, which is
+   * where this gets wired exactly once for every save call site in the app.
+   *
+   * A throw from this callback is swallowed — an advisory channel must never
+   * be able to fail a save that the server already committed.
+   */
+  onSaveAdvisory?: MetadataSaveAdvisoryListener;
 }
 
 export interface MetadataListOptions {
@@ -367,6 +461,32 @@ async function parseError(res: Response): Promise<MetadataError> {
   return err;
 }
 
+/**
+ * Is this the single-item response envelope, as opposed to a metadata document?
+ *
+ * Matched by the PRESENCE of the three keys `GetMetaItemResponseSchema`
+ * declares — `type: string`, `name: string`, and an `item` slot — never by
+ * guessing from the payload's contents. The distinction matters in both
+ * directions:
+ *
+ *  - A metadata document may legitimately carry its own `type` and `name`
+ *    (a view is `{ name, type: 'grid', … }`). Without an `item` key it is the
+ *    body, and unwrapping it would destroy it.
+ *  - A document could carry an `item` property of its own. Without the
+ *    envelope's identity keys it is likewise left whole.
+ *
+ * Key COUNT is deliberately not part of the test: a real envelope also spreads
+ * `MetadataProtectionEnvelopeFields` (`lock`, `provenance`, …), so it routinely
+ * has more than three keys.
+ */
+function isMetaItemEnvelope(
+  value: unknown,
+): value is { type: string; name: string; item: unknown } {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const env = value as Record<string, unknown>;
+  return typeof env.type === 'string' && typeof env.name === 'string' && 'item' in env;
+}
+
 /**
  * MetadataClient — read/write protocol metadata via the framework REST API.
  *
@@ -384,12 +504,15 @@ export class MetadataClient {
   private readonly headers: Record<string, string>;
   /** ADR-0037: when true, reads render the draft-overlaid world. */
   readonly previewDrafts: boolean;
+  /** #4133 — sink for post-save advisory findings; see the config field. */
+  private readonly onSaveAdvisory: MetadataSaveAdvisoryListener | undefined;
 
   constructor(config: MetadataClientConfig) {
     this.base = buildBase(config);
     this.fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
     this.headers = { Accept: 'application/json', ...(config.headers ?? {}) };
     this.previewDrafts = config.previewDrafts === true;
+    this.onSaveAdvisory = config.onSaveAdvisory;
   }
 
   /** Update the client's environment scope at runtime. */
@@ -402,6 +525,11 @@ export class MetadataClient {
       fetch: this.fetchImpl,
       headers: this.headers,
       previewDrafts: this.previewDrafts,
+      // #4133: the advisory sink must survive the clone. `useMetadataClient`
+      // routes EVERY environment-scoped console client through here, so
+      // dropping it would silently disable the channel for exactly the
+      // multi-environment tenants the gate is loudest for.
+      ...(this.onSaveAdvisory ? { onSaveAdvisory: this.onSaveAdvisory } : {}),
     });
   }
 
@@ -423,6 +551,10 @@ export class MetadataClient {
       fetch: this.fetchImpl,
       headers: this.headers,
       previewDrafts,
+      // #4133: carried for the same reason as in `withEnvironment` — preview
+      // mode swaps the whole renderer tree's client, and writes are unaffected
+      // by ADR-0037, so the save door behind this clone still advises.
+      ...(this.onSaveAdvisory ? { onSaveAdvisory: this.onSaveAdvisory } : {}),
     });
   }
 
@@ -488,11 +620,16 @@ export class MetadataClient {
   }
 
   /**
-   * Get a single metadata item. Returns the unwrapped item content
-   * (matching the framework REST handler which calls `res.json(item)`).
-   * Returns `null` on 404 to keep the call-site ergonomic.
+   * Fetch a single metadata item and return the response body EXACTLY as the
+   * server sent it — envelope and all.
+   *
+   * The one transport both {@link get} (which unwraps) and {@link getDraft}
+   * (which does not) sit on, so the two can differ in what they hand back
+   * without differing in how they ask. Private on purpose: the envelope is a
+   * wire detail, and the two published contracts above are the supported ways
+   * to read an item.
    */
-  async get<T = unknown>(
+  private async readItemResponse<T = unknown>(
     type: string,
     name: string,
     options: MetadataGetOptions = {},
@@ -511,24 +648,63 @@ export class MetadataClient {
     return (await res.json()) as T;
   }
 
+  /**
+   * Get a single metadata item. Returns the unwrapped item CONTENT — the
+   * metadata document itself, so `obj.fields` / `obj.label` are reachable
+   * directly.
+   *
+   * The framework answers `GET /meta/:type/:name` with the spec-declared
+   * envelope `{ type, name, item, …protection fields }`
+   * (`GetMetaItemResponseSchema`; objectstack#5563 collapsed this read to that
+   * ONE shape), so the envelope is unwrapped here — at the client boundary,
+   * once — rather than by each caller.
+   *
+   * **This method used to return the envelope while promising the body**
+   * (objectui#4271). Nothing detected the disagreement, because the test
+   * doubles across the repo were written against this docblock: every consumer
+   * reading `obj.fields` got `undefined` in production and a field list in
+   * unit tests. The visible cost was the entire field half of the permission
+   * matrix reporting "No fields registered for this object." for every object,
+   * plus dead RLS CEL autocomplete, an inert report drill-down and a designer
+   * that saved the envelope back over the object body.
+   *
+   * A response that is NOT the envelope (an older server answering the bare
+   * document, or a body of its own shape) passes through untouched, and `null`
+   * still comes back on 404 to keep the call site ergonomic.
+   */
+  async get<T = unknown>(
+    type: string,
+    name: string,
+    options: MetadataGetOptions = {},
+  ): Promise<T | null> {
+    const resp = await this.readItemResponse<unknown>(type, name, options);
+    if (isMetaItemEnvelope(resp)) return (resp.item ?? null) as T | null;
+    return resp as T | null;
+  }
+
   /**
    * Read the pending draft body for an item (`?state=draft`). Returns
    * `null` when there is no draft pending. Draft reads do NOT fall
    * back to the published overlay or the artifact registry — a `null`
    * unambiguously means "nothing to publish".
    *
-   * Note: the framework wraps draft responses in an envelope
-   * `{ type, name, item }` (matching `getMetaItem`); callers should
-   * read `.item` to get the body. The legacy `get()` returns the
-   * unwrapped body, so this method preserves that asymmetry by
-   * returning whatever the server sent.
+   * Note: this method hands back the `{ type, name, item }` envelope the
+   * framework sends, NOT the body — callers read `.item`. That asymmetry with
+   * {@link get} is deliberate and long-standing (the draft envelope's identity
+   * and protection carriers are part of what a draft reader inspects), so it
+   * is preserved by reading the transport directly instead of going through
+   * `get()`'s unwrap. `unwrapDraftBody` (app-shell) and `unwrapViewDraft`
+   * (this package) are the shared helpers for taking the body out.
    */
   async getDraft<T = unknown>(
     type: string,
     name: string,
     options: { packageId?: string } = {},
   ): Promise<T | null> {
-    return this.get<T>(type, name, { state: 'draft', ...(options.packageId ? { packageId: options.packageId } : {}) });
+    return this.readItemResponse<T>(type, name, {
+      state: 'draft',
+      ...(options.packageId ? { packageId: options.packageId } : {}),
+    });
   }
 
   /**
@@ -570,7 +746,28 @@ export class MetadataClient {
       body: JSON.stringify(item),
     });
     if (!res.ok) throw await parseError(res);
-    return (await res.json()) as T;
+    const body = await res.json();
+    // #4133 — the runtime authoring gate's advisory findings (objectstack#7435).
+    // The server emits `advisories` ONLY when non-empty, so a clean save costs
+    // nothing here. Everything below is best-effort by construction: the save
+    // has already been committed server-side and returning it must not depend
+    // on anything the advisory channel does.
+    if (this.onSaveAdvisory) {
+      try {
+        const advisories = readSaveAdvisories(body);
+        if (advisories.length > 0) {
+          this.onSaveAdvisory({
+            type,
+            name,
+            mode: options.mode === 'draft' ? 'draft' : 'publish',
+            advisories,
+          });
+        }
+      } catch {
+        /* an advisory must never turn a committed save into a thrown error */
+      }
+    }
+    return body as T;
   }
 
   /**

package/src/onMutation.test.ts

@@ -78,10 +78,18 @@ describe('ObjectStackAdapter.onMutation', () => {
   });
 
   it('emits a delete event only when the server confirms deletion', async () => {
+    // `success`, not `deleted` (objectstack#5638). This mock is why the bug it
+    // fixed was invisible here: `DeleteDataResult` DECLARED a `deleted` key that
+    // no schema has ever declared and no server path has ever returned, and this
+    // fixture faithfully reproduced the declaration rather than the wire. So the
+    // adapter read `result.deleted`, got `undefined` against a real server —
+    // emitting no event and resolving `undefined` from a `Promise<boolean>` —
+    // while this test stayed green against the fiction. Pinning the shape the
+    // server actually sends is what makes the assertion mean anything.
     const del = vi
       .fn()
-      .mockResolvedValueOnce({ deleted: true })
-      .mockResolvedValueOnce({ deleted: false });
+      .mockResolvedValueOnce({ object: 'showcase_project', id: 'r1', success: true })
+      .mockResolvedValueOnce({ object: 'showcase_project', id: 'r2', success: false });
     const ds = makeDS({ delete: del });
     const events: DataSourceMutationEvent[] = [];
     ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
@@ -94,6 +102,25 @@ describe('ObjectStackAdapter.onMutation', () => {
     ]);
   });
 
+  // REVERSE PIN for objectui#3412 / objectstack#5638. The bug was not that the
+  // guard was missing — it was that the guard read a key the wire never carries,
+  // so it was dead while looking alive. A response spelling the old `deleted`
+  // must therefore emit NOTHING: if someone re-introduces a tolerant
+  // `result.success ?? result.deleted` read, this goes red. Reading both keys is
+  // exactly what contract-first forbids (AGENTS.md #0.1) and what objectstack#5638's
+  // own triage ruled out — the producer has one shape, so the consumer gets one.
+  it('emits nothing for a response carrying the retired `deleted` key', async () => {
+    const del = vi.fn().mockResolvedValue({ object: 'showcase_project', id: 'r1', deleted: true });
+    const ds = makeDS({ delete: del });
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
+
+    const returned = await ds.delete('showcase_project', 'r1');
+
+    expect(events).toEqual([]);
+    expect(returned).toBeUndefined();
+  });
+
   it('emits a single bulk event per bulkUpdate call (not per id)', async () => {
     const updateMany = vi.fn().mockResolvedValue({ succeeded: 3, failed: 0, results: [] });
     const ds = makeDS({ updateMany });

package/src/onSaveAdvisory.test.ts

@@ -0,0 +1,311 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * The SECOND client class's metadata save door must surface the runtime
+ * authoring gate's advisory findings (objectui#4237; backend objectstack#7435).
+ *
+ * `ObjectStackClient.meta.saveItem` writes through the same
+ * `PUT /api/v1/meta/:type/:name` as `MetadataClient.save`, but it is a
+ * different class and #4133/#4236 only covered the other one — every caller
+ * here awaited the call and discarded the response, so an `advisories[]` the
+ * server attached was parsed off the wire and dropped. These pins are the
+ * red-first evidence: with `installSaveAdvisoryInterceptor()` reverted, every
+ * "emits" case below fails because no event is ever produced.
+ *
+ * ## Why these drive a REAL SDK client through a fake `fetch`
+ *
+ * The sibling `onWriteWarning.test.ts` replaces `ds.client` with a stub, which
+ * is right for the data door. It would be wrong here: the whole premise of this
+ * fix is a measurement about the wire — that the SDK's `unwrapResponse` hands
+ * the save body back VERBATIM (it strips its `{ success, data }` envelope only
+ * when the body has a `data` key, and this one does not), so `advisories` is
+ * still at the top level where the shared `readSaveAdvisories` looks for it.
+ * Stubbing `meta` would assume exactly the thing under test. Driving the real
+ * client keeps that measured on every run.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { ObjectStackAdapter } from './index';
+import type {
+  MetadataSaveAdvisoryEvent,
+  RuntimeAuthoringIssue,
+  WriteWarningEvent,
+} from './index';
+
+/** The measured `nightly_purge` finding, in the spec's D3 shape. */
+const PURGE_ADVISORY: RuntimeAuthoringIssue = {
+  severity: 'warning',
+  rule: 'flow/delete-without-filter',
+  where: 'flow "nightly_purge" · node "purge old rows"',
+  path: 'flows[0].nodes[2].config.filters',
+  message: 'this delete_record node sets multi: true with no filter, so it deletes every row',
+  hint: 'add a filter, or set multi: false to delete a single record',
+};
+
+/**
+ * The clean part of a real save response. `success`/`version`/`seq`/`state` are
+ * REQUIRED by `SaveMetaItemResponseSchema` (#5745) — spelled out here because
+ * their presence is what makes the `unwrapResponse` measurement above
+ * meaningful: a `success` boolean with NO sibling `data` key.
+ */
+const CLEAN_BODY = { success: true, version: 'v2', seq: 4, state: 'active' as const };
+
+/** A `fetch` that answers every metadata PUT with `body`, and records the calls. */
+function fetchAnswering(body: unknown) {
+  return vi.fn(async (_input: RequestInfo | URL, _init?: RequestInit) =>
+    new Response(JSON.stringify(body), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    }),
+  );
+}
+
+/**
+ * A connected adapter whose client talks to `fetchImpl`. `connected` is forced
+ * rather than discovered, exactly as the sibling write-warning suite does — the
+ * save door needs no discovery (`getRoute('metadata')` falls back to
+ * `/api/v1/meta`), and skipping it keeps the module-level discovery cache out
+ * of these tests.
+ */
+function makeAdapter(body: unknown) {
+  const fetchImpl = fetchAnswering(body);
+  const ds: any = new ObjectStackAdapter({
+    baseUrl: 'http://test.local',
+    fetch: fetchImpl as unknown as typeof fetch,
+  });
+  ds.connected = true;
+  ds.connectionState = 'connected';
+  return { ds, fetchImpl };
+}
+
+describe('ObjectStackAdapter.onSaveAdvisory — the second client class (#4237)', () => {
+  it('emits the findings a successful save returned', async () => {
+    const { ds } = makeAdapter({ ...CLEAN_BODY, advisories: [PURGE_ADVISORY] });
+    const events: MetadataSaveAdvisoryEvent[] = [];
+    ds.onSaveAdvisory((e: MetadataSaveAdvisoryEvent) => events.push(e));
+
+    await ds.getClient().meta.saveItem('flow', 'nightly_purge', { name: 'nightly_purge' });
+
+    expect(events).toEqual([
+      {
+        type: 'flow',
+        name: 'nightly_purge',
+        mode: 'publish',
+        advisories: [PURGE_ADVISORY],
+      },
+    ]);
+  });
+
+  it('carries rule, message and hint through verbatim — they are server prose', async () => {
+    const { ds } = makeAdapter({ ...CLEAN_BODY, advisories: [PURGE_ADVISORY] });
+    const events: MetadataSaveAdvisoryEvent[] = [];
+    ds.onSaveAdvisory((e: MetadataSaveAdvisoryEvent) => events.push(e));
+
+    await ds.getClient().meta.saveItem('flow', 'nightly_purge', {});
+
+    const finding = events[0]!.advisories[0]!;
+    expect(finding.rule).toBe('flow/delete-without-filter');
+    expect(finding.message).toBe(PURGE_ADVISORY.message);
+    expect(finding.hint).toBe(PURGE_ADVISORY.hint);
+    // Never `error` on this channel — an error-severity finding is a 422.
+    expect(finding.severity).toBe('warning');
+  });
+
+  /**
+   * The response-shape measurement the fix rests on, asserted rather than
+   * assumed: this body is handed back whole. If a future SDK started wrapping
+   * the save response in `{ success, data }`, THIS is the case that goes red
+   * and says so, instead of the advisory channel quietly emitting nothing.
+   */
+  it('hands the caller the save response unchanged — the SDK does not unwrap this body', async () => {
+    const body = { ...CLEAN_BODY, advisories: [PURGE_ADVISORY] };
+    const { ds } = makeAdapter(body);
+
+    const result = await ds.getClient().meta.saveItem('flow', 'nightly_purge', {});
+
+    expect(result).toEqual(body);
+    expect(result.version).toBe('v2');
+    expect(result.advisories).toEqual([PURGE_ADVISORY]);
+  });
+
+  it('says nothing on a clean save — the server omits the key entirely', async () => {
+    const { ds } = makeAdapter(CLEAN_BODY);
+    const events: MetadataSaveAdvisoryEvent[] = [];
+    ds.onSaveAdvisory((e: MetadataSaveAdvisoryEvent) => events.push(e));
+
+    await ds.getClient().meta.saveItem('object', 'account', { name: 'account' });
+
+    expect(events).toEqual([]);
+  });
+
+  it('says nothing when the array is present but empty', async () => {
+    const { ds } = makeAdapter({ ...CLEAN_BODY, advisories: [] });
+    const events: MetadataSaveAdvisoryEvent[] = [];
+    ds.onSaveAdvisory((e: MetadataSaveAdvisoryEvent) => events.push(e));
+
+    await ds.getClient().meta.saveItem('object', 'account', {});
+
+    expect(events).toEqual([]);
+  });
+
+  it('drops half-shaped findings rather than rendering blanks at the author', async () => {
+    const { ds } = makeAdapter({
+      ...CLEAN_BODY,
+      advisories: [PURGE_ADVISORY, { rule: 'only-a-rule' }, null, 'string'],
+    });
+    const events: MetadataSaveAdvisoryEvent[] = [];
+    ds.onSaveAdvisory((e: MetadataSaveAdvisoryEvent) => events.push(e));
+
+    await ds.getClient().meta.saveItem('flow', 'nightly_purge', {});
+
+    // The SAME reader `MetadataClient.save` uses — one reader, two call sites.
+    expect(events[0]!.advisories).toEqual([PURGE_ADVISORY]);
+  });
+
+  it('a throwing listener never fails a save the server already committed', async () => {
+    const { ds } = makeAdapter({ ...CLEAN_BODY, advisories: [PURGE_ADVISORY] });
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const seen: MetadataSaveAdvisoryEvent[] = [];
+    ds.onSaveAdvisory(() => {
+      throw new Error('renderer exploded');
+    });
+    // Registered second: a throwing listener must not starve the others.
+    ds.onSaveAdvisory((e: MetadataSaveAdvisoryEvent) => seen.push(e));
+
+    await expect(
+      ds.getClient().meta.saveItem('flow', 'nightly_purge', {}),
+    ).resolves.toBeTruthy();
+    expect(seen).toHaveLength(1);
+    warn.mockRestore();
+  });
+
+  it('unsubscribes', async () => {
+    const { ds } = makeAdapter({ ...CLEAN_BODY, advisories: [PURGE_ADVISORY] });
+    const events: MetadataSaveAdvisoryEvent[] = [];
+    const off = ds.onSaveAdvisory((e: MetadataSaveAdvisoryEvent) => events.push(e));
+
+    await ds.getClient().meta.saveItem('flow', 'a', {});
+    off();
+    await ds.getClient().meta.saveItem('flow', 'b', {});
+
+    expect(events).toHaveLength(1);
+  });
+
+  /**
+   * Control for the #4133/#4236 sibling channel: a metadata save is NOT a
+   * record write, and must not appear on the dropped-fields channel. This is
+   * what makes the "existing `onWriteWarning` consumers unchanged" claim
+   * checkable rather than asserted.
+   */
+  it('does not leak onto the write-warning channel', async () => {
+    const { ds } = makeAdapter({ ...CLEAN_BODY, advisories: [PURGE_ADVISORY] });
+    const warnings: WriteWarningEvent[] = [];
+    ds.onWriteWarning((e: WriteWarningEvent) => warnings.push(e));
+
+    await ds.getClient().meta.saveItem('flow', 'nightly_purge', {});
+
+    expect(warnings).toEqual([]);
+  });
+});
+
+/**
+ * Draft-door honesty (D1), carried over from #4236's finding.
+ *
+ * Drafts are never gated — the framework returns at
+ * `runtime-authoring-gate.ts`'s early return:
+ *
+ *     // D1 — drafts are never gated. Publishing one runs this same function.
+ *     if (args.state !== 'active') return null;
+ *
+ * so a draft save produces no findings at all rather than producing some that
+ * get withheld. Unlike the other client class, THIS one has no draft door to
+ * begin with: the SDK's `saveItem(type, name, item)` takes no mode, so every
+ * caller enumerated on #4237 writes the active door and the gate does run for
+ * all of them. `mode` is therefore read off the response's own `state`.
+ */
+describe('save-advisory mode reflects the door the server reports (D1)', () => {
+  it('a draft-state response with no findings emits nothing — the gate never ran', async () => {
+    const { ds } = makeAdapter({ ...CLEAN_BODY, state: 'draft' });
+    const events: MetadataSaveAdvisoryEvent[] = [];
+    ds.onSaveAdvisory((e: MetadataSaveAdvisoryEvent) => events.push(e));
+
+    await ds.getClient().meta.saveItem('flow', 'nightly_purge', {});
+
+    expect(events).toEqual([]);
+  });
+
+  it('labels the mode from the response state when a draft does somehow advise', async () => {
+    // Not reachable through today's server (see D1 above), but the event must
+    // tell the truth about which door it came through rather than hard-coding
+    // one, so the field is pinned on its own.
+    const { ds } = makeAdapter({
+      ...CLEAN_BODY,
+      state: 'draft',
+      advisories: [PURGE_ADVISORY],
+    });
+    const events: MetadataSaveAdvisoryEvent[] = [];
+    ds.onSaveAdvisory((e: MetadataSaveAdvisoryEvent) => events.push(e));
+
+    await ds.getClient().meta.saveItem('flow', 'nightly_purge', {});
+
+    expect(events[0]!.mode).toBe('draft');
+  });
+});
+
+/**
+ * Caller coverage. The point of putting ONE emitter at the client seam is that
+ * the enumerated call sites need no edit — so the pins that matter are the ones
+ * that never mention the interceptor.
+ */
+describe('the enumerated callers are covered without a per-site edit', () => {
+  it("covers the adapter's own view save path (updateViewConfig)", async () => {
+    const { ds } = makeAdapter({ ...CLEAN_BODY, advisories: [PURGE_ADVISORY] });
+    const events: MetadataSaveAdvisoryEvent[] = [];
+    ds.onSaveAdvisory((e: MetadataSaveAdvisoryEvent) => events.push(e));
+
+    await ds.updateViewConfig('lead', 'all_leads', { object: 'lead' });
+
+    expect(events).toHaveLength(1);
+    expect(events[0]!.type).toBe('view');
+    expect(events[0]!.name).toBe('all_leads');
+  });
+
+  it("covers the adapter's own dashboard save path (updateDashboard)", async () => {
+    const { ds } = makeAdapter({ ...CLEAN_BODY, advisories: [PURGE_ADVISORY] });
+    const events: MetadataSaveAdvisoryEvent[] = [];
+    ds.onSaveAdvisory((e: MetadataSaveAdvisoryEvent) => events.push(e));
+
+    await ds.updateDashboard('crm_overview_dashboard', { widgets: [] });
+
+    expect(events).toHaveLength(1);
+    expect(events[0]!.type).toBe('dashboard');
+    expect(events[0]!.name).toBe('crm_overview_dashboard');
+  });
+
+  /**
+   * `getClient()` hands back the adapter's own long-lived instance, which is
+   * how every caller OUTSIDE this package reaches the save door
+   * (`MetadataService`, `useNavigationSync`, plugin-designer's app wizard).
+   * If that ever started returning a fresh or wrapped client, the interceptor
+   * would stop covering them — so the identity is pinned here.
+   */
+  it('getClient() is the intercepted instance every external caller uses', async () => {
+    const { ds } = makeAdapter({ ...CLEAN_BODY, advisories: [PURGE_ADVISORY] });
+    const events: MetadataSaveAdvisoryEvent[] = [];
+    ds.onSaveAdvisory((e: MetadataSaveAdvisoryEvent) => events.push(e));
+
+    expect(ds.getClient()).toBe(ds.getClient());
+
+    // The `saveItem('app', …)` shape `useNavigationSync` and the plugin-designer
+    // app wizard both use.
+    await ds.getClient().meta.saveItem('app', 'crm', { name: 'crm' });
+
+    expect(events[0]).toMatchObject({ type: 'app', name: 'crm' });
+  });
+});