@object-ui/data-objectstack 17.2.0 → 17.5.0

package/src/listViewOverrides.test.ts

@@ -0,0 +1,241 @@
+/**
+ * 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.
+ */
+
+/**
+ * objectui#3774 — the view-override read and write must share one key space.
+ *
+ * `updateViewConfig` persists a personalization (density, column widths, sort,
+ * hidden columns, inlineEdit …) as `PUT /api/v1/meta/view/{viewId}`, i.e. a
+ * `sys_metadata` row with `type='view'`. `listViewOverrides` used to enumerate
+ * `GET /api/v1/meta/{objectName}` — the OBJECT name in the metadata TYPE slot.
+ * The two key spaces are disjoint, so the batch map came back empty for every
+ * object forever and every saved preference read back as "setting didn't save".
+ *
+ * The measurement that picked the fix: `GET /meta/:type` accepts `?package=`
+ * and `?preview=draft` and NOTHING else (framework
+ * `packages/rest/src/rest-server.ts`, and `client.meta.getItems(type, {
+ * packageId })`). There is no `?object=` to push the filter into, so the
+ * correct route is the one `listViews()` already uses over the same rows:
+ * enumerate `type='view'` once, narrow to the object client-side.
+ *
+ * The suite is written round-trip on purpose — a stub `sys_metadata` that the
+ * adapter's own write path fills and its own read path drains. Asserting the
+ * read against a hand-written fixture would have stayed green through the
+ * entire bug, because the fixture is where the namespace mistake lived.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { ObjectStackAdapter } from './index';
+
+/** A stub metadata store keyed the way `sys_metadata` is: `type` + `name`. */
+function makeMetaStore() {
+  const rows = new Map<string, any>();
+  const getItemsTypes: string[] = [];
+
+  const meta = {
+    getItems: vi.fn(async (type: string) => {
+      getItemsTypes.push(type);
+      const items = [...rows.entries()]
+        .filter(([k]) => k.startsWith(`${type}::`))
+        .map(([, v]) => v);
+      return { type, items };
+    }),
+    getItem: vi.fn(async (type: string, name: string) => {
+      const item = rows.get(`${type}::${name}`);
+      if (!item) {
+        const err: any = new Error(`Not found: ${type}/${name}`);
+        err.status = 404;
+        throw err;
+      }
+      return { type, name, item };
+    }),
+    saveItem: vi.fn(async (type: string, name: string, item: any) => {
+      rows.set(`${type}::${name}`, { ...item });
+      return { success: true, item: rows.get(`${type}::${name}`) };
+    }),
+  };
+
+  return { meta, rows, getItemsTypes };
+}
+
+function makeDS(meta: any) {
+  const ds: any = new ObjectStackAdapter({
+    baseUrl: 'http://test.local',
+    fetch: vi.fn(async () =>
+      new Response(JSON.stringify({ success: true, data: { capabilities: {}, routes: {} } }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      })),
+  });
+  ds.connected = true;
+  ds.connectionState = 'connected';
+  ds.client = { meta };
+  return ds;
+}
+
+/**
+ * What ObjectView's `persistViewPatch` actually sends on a density toggle +
+ * column sort: the view's raw config plus the personalization state. The
+ * adapter stamps `object` / `name` on top (and the framework's overlay heals
+ * the same identity fields onto rows that lack them — objectstack#2555).
+ */
+const PERSONALIZATION = {
+  type: 'grid',
+  data: { provider: 'object', object: 'crm_lead' },
+  columns: ['name', 'status'],
+  density: 'compact',
+  sort: [{ field: 'created_at', order: 'desc' }],
+};
+
+describe('ObjectStackAdapter.listViewOverrides — read/write key space (#3774)', () => {
+  it('round-trips: a config saved through updateViewConfig comes back from listViewOverrides', async () => {
+    const { meta, getItemsTypes } = makeMetaStore();
+    const ds = makeDS(meta);
+
+    await ds.updateViewConfig('crm_lead', 'crm_lead.all', { ...PERSONALIZATION });
+    const map = await ds.listViewOverrides('crm_lead');
+
+    // The bug in one assertion: pre-fix this was `{}`.
+    expect(Object.keys(map)).toEqual(['crm_lead.all']);
+    expect(map['crm_lead.all']).toMatchObject({
+      name: 'crm_lead.all',
+      object: 'crm_lead',
+      density: 'compact',
+      sort: [{ field: 'created_at', order: 'desc' }],
+    });
+
+    // …and the type slot itself, which is the actual defect. The write went to
+    // `saveItem('view', …)`; the read must enumerate the SAME type.
+    expect(meta.saveItem).toHaveBeenCalledWith('view', 'crm_lead.all', expect.any(Object));
+    expect(getItemsTypes).toEqual(['view']);
+    expect(getItemsTypes).not.toContain('crm_lead');
+  });
+
+  it('keys the map by the identity getView reads back by (drop-in for the per-view fetch)', async () => {
+    const { meta } = makeMetaStore();
+    const ds = makeDS(meta);
+
+    await ds.updateViewConfig('crm_lead', 'crm_lead.all', { ...PERSONALIZATION });
+
+    const batched = (await ds.listViewOverrides('crm_lead'))['crm_lead.all'];
+    const perView = await ds.getView('crm_lead', 'crm_lead.all');
+
+    // Same key space, same document — that equality is what lets a caller
+    // substitute one call for N without changing what it renders.
+    expect(batched).toEqual(perView);
+  });
+
+  it('finds an override whose only object association is the top-level `object` stamp', async () => {
+    const { meta } = makeMetaStore();
+    const ds = makeDS(meta);
+
+    // A saved view with no `data.object` (e.g. a kanban personalization whose
+    // provider block was never sent) — `updateViewConfig`'s stamp is the only
+    // association, and it must be enough.
+    await ds.updateViewConfig('crm_lead', 'crm_lead.pipeline', { type: 'kanban', density: 'comfortable' });
+    const map = await ds.listViewOverrides('crm_lead');
+
+    expect(map['crm_lead.pipeline']).toMatchObject({ object: 'crm_lead', density: 'comfortable' });
+  });
+
+  it('narrows the shared `type=view` enumeration to the requested object', async () => {
+    const { meta } = makeMetaStore();
+    const ds = makeDS(meta);
+
+    await ds.updateViewConfig('crm_lead', 'crm_lead.all', { ...PERSONALIZATION });
+    await ds.updateViewConfig('crm_account', 'crm_account.all', {
+      type: 'grid', data: { provider: 'object', object: 'crm_account' }, density: 'compact',
+    });
+
+    expect(Object.keys(await ds.listViewOverrides('crm_lead'))).toEqual(['crm_lead.all']);
+    expect(Object.keys(await ds.listViewOverrides('crm_account'))).toEqual(['crm_account.all']);
+  });
+
+  it('skips rows the enumeration returns without a name (nothing can address them)', async () => {
+    const { meta, rows } = makeMetaStore();
+    const ds = makeDS(meta);
+    rows.set('view::anon', { object: 'crm_lead', density: 'compact' });
+
+    expect(await ds.listViewOverrides('crm_lead')).toEqual({});
+  });
+});
+
+describe('ObjectStackAdapter.listViewOverrides — empty vs unknown (#3774)', () => {
+  it('an EMPTY successful enumeration resolves to {} — that answer is authoritative', async () => {
+    const { meta } = makeMetaStore();
+    const ds = makeDS(meta);
+
+    // No overrides exist for this object. The caller may trust this and skip
+    // the per-view reads; the batch optimization depends on it not throwing.
+    await expect(ds.listViewOverrides('crm_lead')).resolves.toEqual({});
+  });
+
+  it('a FAILING enumeration rejects — it must not masquerade as an empty map', async () => {
+    const { meta } = makeMetaStore();
+    meta.getItems.mockRejectedValueOnce(new Error('503 metadata store unavailable'));
+    const ds = makeDS(meta);
+
+    // Pre-fix this resolved to `{}`, which is indistinguishable from the
+    // authoritative "no overrides" above — that is what made ObjectView's
+    // per-view getView fallback unreachable code.
+    await expect(ds.listViewOverrides('crm_lead')).rejects.toThrow('503 metadata store unavailable');
+  });
+
+  it('a rejection is not cached — the next call re-reads instead of pinning the failure', async () => {
+    const { meta } = makeMetaStore();
+    const ds = makeDS(meta);
+    await ds.updateViewConfig('crm_lead', 'crm_lead.all', { ...PERSONALIZATION });
+    meta.getItems.mockRejectedValueOnce(new Error('transient'));
+
+    await expect(ds.listViewOverrides('crm_lead')).rejects.toThrow('transient');
+    // The store recovered; a cached failure would have starved the view of its
+    // overrides for the whole TTL.
+    expect(Object.keys(await ds.listViewOverrides('crm_lead'))).toEqual(['crm_lead.all']);
+  });
+});
+
+describe('ObjectStackAdapter.listViewOverrides — wire route (#3774)', () => {
+  /** Let the REAL `client.meta` run so the request URL is observed, not assumed. */
+  function makeHttpDS(items: any[]) {
+    const urls: string[] = [];
+    const fetchImpl = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      urls.push(url);
+      if (url.includes('/meta/')) {
+        return new Response(JSON.stringify({ type: 'view', items }), {
+          status: 200, headers: { 'Content-Type': 'application/json' },
+        });
+      }
+      return new Response(JSON.stringify({ success: true, data: { capabilities: {}, routes: {} } }), {
+        status: 200, headers: { 'Content-Type': 'application/json' },
+      });
+    });
+    const ds: any = new ObjectStackAdapter({ baseUrl: 'http://test.local', fetch: fetchImpl });
+    ds.connected = true;
+    ds.connectionState = 'connected';
+    return { ds, urls };
+  }
+
+  it('GETs the view TYPE, never a route built from the object name', async () => {
+    const { ds, urls } = makeHttpDS([
+      { name: 'crm_lead.all', object: 'crm_lead', ...PERSONALIZATION },
+    ]);
+
+    const map = await ds.listViewOverrides('crm_lead');
+    expect(map['crm_lead.all']).toMatchObject({ density: 'compact' });
+
+    const metaUrls = urls.filter((u) => u.includes('/meta/'));
+    expect(metaUrls.length).toBeGreaterThan(0);
+    for (const u of metaUrls) {
+      expect(u).toMatch(/\/meta\/view(\?|$)/);
+      // The pre-fix route. Pinned by shape so it cannot come back as
+      // `/meta/crm_lead` under a different spelling of the same mistake.
+      expect(u).not.toContain('/meta/crm_lead');
+    }
+  });
+});

package/src/metadata-client.get-envelope.test.ts

@@ -0,0 +1,171 @@
+/**
+ * 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.
+ */
+
+/**
+ * objectui#4271 — `MetadataClient.get()` honors its documented unwrapped-body
+ * contract.
+ *
+ * The framework answers `GET /meta/:type/:name` with the spec-declared
+ * envelope `{ type, name, item, ...protection fields }`
+ * (`GetMetaItemResponseSchema`; objectstack#5563 collapsed the read to that ONE
+ * shape). `get()` used to hand that envelope straight back while its own
+ * docblock promised the unwrapped body — so every consumer reading `obj.fields`
+ * saw `undefined`, which is how the whole field half of the permission matrix
+ * went dead for every object.
+ *
+ * The asymmetry that IS real and stays: `getDraft()` documents the envelope and
+ * its callers read `.item`, so it must keep returning what the server sent.
+ * A11/A10 below are the pair that pins both halves.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { MetadataClient, type MetadataError } from './metadata-client';
+
+function mockFetch(handler: (url: string, init?: RequestInit) => Promise<Response>): typeof fetch {
+  return vi.fn(handler) as unknown as typeof fetch;
+}
+
+function jsonResponse(body: unknown, init?: ResponseInit): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+    ...init,
+  });
+}
+
+/** A client whose single-item read answers `body`, recording the URLs it hit. */
+function clientAnswering(body: unknown, init?: ResponseInit) {
+  const urls: string[] = [];
+  const c = new MetadataClient({
+    baseUrl: 'http://localhost:3000',
+    fetch: mockFetch(async (url) => {
+      urls.push(url);
+      return init ? new Response(JSON.stringify(body), init) : jsonResponse(body);
+    }),
+  });
+  return { c, urls };
+}
+
+/** The card's live shape: 21 fields under `item`, as showcase_project answers. */
+const OBJECT_BODY = {
+  name: 'showcase_project',
+  label: 'Project',
+  fields: { name: { type: 'text' }, stage: { type: 'select' } },
+};
+const ENVELOPE = { type: 'object', name: 'showcase_project', item: OBJECT_BODY };
+
+describe('objectui#4271 · MetadataClient.get() unwraps the spec envelope', () => {
+  it('A1: unwraps `{type,name,item}` to the item body', async () => {
+    const { c } = clientAnswering(ENVELOPE);
+    const obj = await c.get<Record<string, unknown>>('object', 'showcase_project');
+    expect(obj).toEqual(OBJECT_BODY);
+    // The headline consequence: the field map is reachable again.
+    expect(Object.keys((obj as any)?.fields ?? {})).toEqual(['name', 'stage']);
+  });
+
+  it('A2: unwraps when the ADR-0008 protection carriers ride along', async () => {
+    // `GetMetaItemResponseSchema` spreads MetadataProtectionEnvelopeFields, so
+    // a real envelope carries more than three keys. Unwrapping must not be
+    // conditioned on the key COUNT.
+    const { c } = clientAnswering({
+      ...ENVELOPE,
+      lock: { locked: false, reason: 'ok' },
+      provenance: { origin: 'package' },
+    });
+    expect(await c.get('object', 'showcase_project')).toEqual(OBJECT_BODY);
+  });
+
+  it('A3: an envelope carrying a null item reads as null', async () => {
+    const { c } = clientAnswering({ type: 'object', name: 'ghost', item: null });
+    expect(await c.get('object', 'ghost')).toBeNull();
+  });
+});
+
+describe('objectui#4271 · non-envelope responses pass through UNCHANGED', () => {
+  it('A4: a bare body (older server / already-unwrapped) is returned as-is', async () => {
+    const { c } = clientAnswering(OBJECT_BODY);
+    expect(await c.get('object', 'showcase_project')).toEqual(OBJECT_BODY);
+  });
+
+  it('A5: type+name WITHOUT an `item` key is not unwrapped', async () => {
+    // A metadata document may legitimately carry `type` and `name` of its own
+    // (a view is `{name, type: "grid", ...}`). Absent `item`, it is the body.
+    const view = { name: 'all_projects', type: 'grid', columns: ['name'] };
+    const { c } = clientAnswering(view);
+    expect(await c.get('view', 'all_projects')).toEqual(view);
+  });
+
+  it('A6: an `item` key WITHOUT the envelope identity is not unwrapped', async () => {
+    // Presence-checked against the spec shape, not duck-guessed off `item`
+    // alone — a body whose own schema has an `item` property stays whole.
+    const body = { name: 'cart', item: { sku: 'x' } };
+    const { c } = clientAnswering(body);
+    expect(await c.get('object', 'cart')).toEqual(body);
+  });
+
+  it('A7: an array response passes through', async () => {
+    const { c } = clientAnswering([{ name: 'a' }]);
+    expect(await c.get('object', 'weird')).toEqual([{ name: 'a' }]);
+  });
+
+  it('A8: 404 still reads as null', async () => {
+    const { c } = clientAnswering({}, { status: 404 });
+    expect(await c.get('object', 'missing')).toBeNull();
+  });
+
+  it('A9: error responses still throw with status, code and message intact', async () => {
+    const { c } = clientAnswering(
+      { error: { code: 'RESOURCE_FORBIDDEN', message: 'Nope.' } },
+      { status: 403, headers: { 'content-type': 'application/json' } },
+    );
+    await expect(c.get('object', 'secret')).rejects.toThrow('Nope.');
+    const err = await c.get('object', 'secret').catch((e: MetadataError) => e);
+    expect((err as MetadataError).status).toBe(403);
+    expect((err as MetadataError).code).toBe('RESOURCE_FORBIDDEN');
+  });
+});
+
+describe('objectui#4271 · the getDraft() envelope asymmetry is preserved', () => {
+  it('A10: getDraft() returns the RAW envelope, as its docblock promises', async () => {
+    // Load-bearing: ~11 call sites read `.item` off getDraft (StudioDesignSurface,
+    // ResourceEditPage, PackageOwdOverviewPanel, ObjectHooksPanel,
+    // PermissionMatrixEditor). Routing getDraft through the unwrapping get()
+    // would silently empty every one of them.
+    const draftEnvelope = { type: 'object', name: 'showcase_project', item: OBJECT_BODY };
+    const { c, urls } = clientAnswering(draftEnvelope);
+    const draft = await c.getDraft<Record<string, unknown>>('object', 'showcase_project');
+    expect(draft).toEqual(draftEnvelope);
+    expect((draft as any)?.item).toEqual(OBJECT_BODY);
+    expect(urls[0]).toBe('http://localhost:3000/api/v1/meta/object/showcase_project?state=draft');
+  });
+
+  it('A11: get(state:draft) unwraps like any other get()', async () => {
+    // The SHAPE follows the method's published contract, not the query param:
+    // `get()` promises the body on every path it serves.
+    const { c, urls } = clientAnswering(ENVELOPE);
+    expect(await c.get('object', 'showcase_project', { state: 'draft' })).toEqual(OBJECT_BODY);
+    expect(urls[0]).toBe('http://localhost:3000/api/v1/meta/object/showcase_project?state=draft');
+  });
+
+  it('A12: URL construction is untouched by the unwrap', async () => {
+    const { c, urls } = clientAnswering(ENVELOPE);
+    await c.get('object', 'has spaces', { packageId: 'app.crm' });
+    expect(urls[0]).toBe('http://localhost:3000/api/v1/meta/object/has%20spaces?package=app.crm');
+    const preview = new MetadataClient({
+      baseUrl: 'http://localhost:3000',
+      previewDrafts: true,
+      fetch: mockFetch(async (url) => {
+        urls.push(url);
+        return jsonResponse(ENVELOPE);
+      }),
+    });
+    // The overlay flag still rides, and the preview read unwraps too.
+    expect(await preview.get('object', 'showcase_project')).toEqual(OBJECT_BODY);
+    expect(urls[1]).toBe('http://localhost:3000/api/v1/meta/object/showcase_project?preview=draft');
+  });
+});

package/src/metadata-client.saveAdvisories.test.ts

@@ -0,0 +1,226 @@
+/**
+ * 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.
+ */
+
+/**
+ * `MetadataClient.save` must surface the runtime authoring gate's advisory
+ * findings (objectui#4133; backend objectstack#7435, landed as `89d7b35a7`).
+ *
+ * The save SUCCEEDED — a 200, the row persisted, the version bumped. The gate
+ * simply noticed something worth telling the author, and before this the
+ * findings were parsed off the wire and dropped on the floor client-side. These
+ * pins are the red-first evidence: with the emit removed from `save()`, the
+ * "renders the findings" cases below fail because no event ever arrives.
+ *
+ * The measured example the card is built on: a `nightly_purge` flow whose only
+ * defect is a `delete_record` node with `multi: true` and no filter yields
+ * `errors = 0 / advisories = 1` — a 200 the author currently learns nothing from.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import {
+  MetadataClient,
+  readSaveAdvisories,
+  type MetadataSaveAdvisoryEvent,
+  type RuntimeAuthoringIssue,
+} from './metadata-client';
+
+/** 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',
+};
+
+function saveResponse(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+function clientWith(
+  responseBody: unknown,
+  onSaveAdvisory?: (ev: MetadataSaveAdvisoryEvent) => void,
+) {
+  return new MetadataClient({
+    baseUrl: 'http://test.local',
+    fetch: vi.fn(async () => saveResponse(responseBody)) as unknown as typeof fetch,
+    ...(onSaveAdvisory ? { onSaveAdvisory } : {}),
+  });
+}
+
+const CLEAN_BODY = { success: true, version: 'v2', seq: 4, state: 'active' };
+
+describe('MetadataClient.save — runtime authoring gate advisories (#4133)', () => {
+  it('emits the findings a successful save returned', async () => {
+    const events: MetadataSaveAdvisoryEvent[] = [];
+    const client = clientWith(
+      { ...CLEAN_BODY, advisories: [PURGE_ADVISORY] },
+      (e) => events.push(e),
+    );
+
+    await client.save('flow', 'nightly_purge', { name: 'nightly_purge' });
+
+    expect(events).toHaveLength(1);
+    expect(events[0]).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 events: MetadataSaveAdvisoryEvent[] = [];
+    const client = clientWith(
+      { ...CLEAN_BODY, advisories: [PURGE_ADVISORY] },
+      (e) => events.push(e),
+    );
+
+    await client.save('flow', 'nightly_purge', {});
+
+    const [finding] = events[0]!.advisories;
+    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');
+  });
+
+  it('says nothing on a clean save — the server omits the key entirely', async () => {
+    const events: MetadataSaveAdvisoryEvent[] = [];
+    const client = clientWith(CLEAN_BODY, (e) => events.push(e));
+
+    await client.save('object', 'account', { name: 'account' });
+
+    expect(events).toEqual([]);
+  });
+
+  it('says nothing when the array is present but empty', async () => {
+    const events: MetadataSaveAdvisoryEvent[] = [];
+    const client = clientWith({ ...CLEAN_BODY, advisories: [] }, (e) => events.push(e));
+
+    await client.save('object', 'account', {});
+
+    expect(events).toEqual([]);
+  });
+
+  it('still returns the save response unchanged', async () => {
+    const body = { ...CLEAN_BODY, advisories: [PURGE_ADVISORY] };
+    const client = clientWith(body, () => {});
+
+    const result = await client.save('flow', 'nightly_purge', {});
+
+    expect(result).toEqual(body);
+  });
+
+  it('a throwing sink never fails a save the server already committed', async () => {
+    const client = clientWith({ ...CLEAN_BODY, advisories: [PURGE_ADVISORY] }, () => {
+      throw new Error('renderer exploded');
+    });
+
+    await expect(client.save('flow', 'nightly_purge', {})).resolves.toBeTruthy();
+  });
+
+  /**
+   * The honest control for the coverage statement (#4133 requirement 3).
+   *
+   * A `mode: 'draft'` save is a PUT through the same save door, but the
+   * framework's gate returns at its D1 early-return before running a single
+   * rule — `runtime-authoring-gate.ts`:
+   *
+   *     // D1 — drafts are never gated. Publishing one runs this same function.
+   *     if (args.state !== 'active') return null;
+   *
+   * so the server produces no findings and the response carries no key. The
+   * client is not what suppresses this; there is nothing to suppress. Pinned
+   * because Studio's designer saves as draft on EVERY edit, which is why the
+   * affordance renders nothing on that flow today.
+   */
+  it('a draft save carries no findings — the gate never ran (D1)', async () => {
+    const events: MetadataSaveAdvisoryEvent[] = [];
+    const client = clientWith({ ...CLEAN_BODY, state: 'draft' }, (e) => events.push(e));
+
+    await client.save('flow', 'nightly_purge', {}, { mode: 'draft' });
+
+    expect(events).toEqual([]);
+  });
+
+  it('labels the mode when a draft save does somehow advise', async () => {
+    // Not reachable through today's server (see D1 above), but the event's
+    // `mode` must tell the truth about which door it came through rather than
+    // hard-coding one, so the field is pinned on its own.
+    const events: MetadataSaveAdvisoryEvent[] = [];
+    const client = clientWith(
+      { ...CLEAN_BODY, state: 'draft', advisories: [PURGE_ADVISORY] },
+      (e) => events.push(e),
+    );
+
+    await client.save('flow', 'nightly_purge', {}, { mode: 'draft' });
+
+    expect(events[0]!.mode).toBe('draft');
+  });
+
+  it('survives the withEnvironment clone — console clients are all env-scoped', async () => {
+    const events: MetadataSaveAdvisoryEvent[] = [];
+    const base = new MetadataClient({
+      baseUrl: 'http://test.local',
+      fetch: vi.fn(async () =>
+        saveResponse({ ...CLEAN_BODY, advisories: [PURGE_ADVISORY] }),
+      ) as unknown as typeof fetch,
+      onSaveAdvisory: (e) => events.push(e),
+    });
+
+    await base.withEnvironment('env_1').save('flow', 'nightly_purge', {});
+
+    expect(events).toHaveLength(1);
+  });
+
+  it('survives the withPreviewDrafts clone', async () => {
+    const events: MetadataSaveAdvisoryEvent[] = [];
+    const base = new MetadataClient({
+      baseUrl: 'http://test.local',
+      fetch: vi.fn(async () =>
+        saveResponse({ ...CLEAN_BODY, advisories: [PURGE_ADVISORY] }),
+      ) as unknown as typeof fetch,
+      onSaveAdvisory: (e) => events.push(e),
+    });
+
+    await base.withPreviewDrafts(true).save('flow', 'nightly_purge', {});
+
+    expect(events).toHaveLength(1);
+  });
+});
+
+describe('readSaveAdvisories', () => {
+  it('reads a well-formed array', () => {
+    expect(readSaveAdvisories({ advisories: [PURGE_ADVISORY] })).toEqual([PURGE_ADVISORY]);
+  });
+
+  it('returns empty for a response with no advisories key', () => {
+    expect(readSaveAdvisories(CLEAN_BODY)).toEqual([]);
+  });
+
+  it.each([
+    ['null body', null],
+    ['a string body', 'nope'],
+    ['a non-array advisories', { advisories: { rule: 'x' } }],
+  ])('returns empty for %s', (_label, body) => {
+    expect(readSaveAdvisories(body)).toEqual([]);
+  });
+
+  it('drops half-shaped findings rather than rendering blanks at the author', () => {
+    const out = readSaveAdvisories({
+      advisories: [PURGE_ADVISORY, { rule: 'only-a-rule' }, null, 'string'],
+    });
+    expect(out).toEqual([PURGE_ADVISORY]);
+  });
+});