@object-ui/data-objectstack 17.2.0 → 17.5.0

package/src/deleteView.homes.test.ts

@@ -0,0 +1,389 @@
+/**
+ * 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.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { ObjectStackAdapter } from './index';
+import { MetadataClient } from './metadata-client';
+
+/**
+ * `deleteView` removes every home the view has (#4479).
+ *
+ * A view has two possible homes — the pending per-item DRAFT
+ * (`DELETE /meta/view/:name?state=draft`) and the PUBLISHED overlay
+ * (`DELETE /meta/view/:name`) — and `deleteView` used to address only the
+ * published one. The three cases, and what each used to do:
+ *
+ * | case               | before #4479                                        |
+ * |--------------------|-----------------------------------------------------|
+ * | draft-only view    | BUG — hits the published overlay, `reset:false`, the |
+ * |                    | draft survives and the tab is back after reload      |
+ * | published-only     | correct — `reset:true`, tab gone                     |
+ * | published + draft  | ACCIDENTALLY correct — the published row goes, so    |
+ * |                    | the tab goes; the orphan draft is left behind        |
+ *
+ * The third row is why the mirror of #4139 is NOT mechanical.
+ * `persistRuntimeMetadata` (app-shell) stages **every** runtime edit as a
+ * draft, so "publish a view, then edit it" routinely produces a pair — and a
+ * naive draft-FIRST-only mirror would have discarded just the draft there,
+ * silently downgrading **Delete view** into **Discard draft**, which is a
+ * different operation that already exists (`discardRuntimeDraft`).
+ *
+ * The ruling on #4479: delete BOTH homes, draft first. Draft first because a
+ * failure between the two calls then leaves the PUBLISHED overlay intact and
+ * the operation cleanly retryable — the reverse order strands a draft-only
+ * view, which is this card's original bug shape.
+ *
+ * ## The wire these pins model
+ *
+ * Every receipt below is the framework's own, read verbatim from
+ * `packages/metadata-protocol/src/protocol.ts` (`deleteMetaItem`) — the
+ * no-row branch and the delete-ful branch. Both no-row answers are a **200**
+ * carrying `reset:false`, NOT a 404:
+ *
+ * - no draft pending  -> `{success:true, reset:false, message:"No pending draft for view/x."}`
+ * - no published row  -> `{success:true, reset:false, message:"No view 'x' found — nothing to delete."}`
+ *
+ * That measurement is what makes a blind two-call implementation legitimate
+ * here: neither "missing home" answer is an error, so there is nothing for a
+ * probe to protect against and the probe `updateView` needs (its read must
+ * resolve the row it is about to merge onto) has no counterpart for a delete.
+ *
+ * Nothing here mocks `deleteView`. The adapter is real and drives a
+ * wire-shaped `fetch`; the SDK stand-in on `ds.client.meta.deleteItem`
+ * mirrors the real client's transport (same URL, same `unwrapResponse`) so
+ * that the pins address the REQUEST, not the transport that issued it.
+ */
+
+const VIEW = 'account.my_pipeline';
+
+/** Framework receipt: a draft row existed and was discarded. */
+const DRAFT_DISCARDED = {
+  success: true,
+  reset: true,
+  seq: 41,
+  message: `Draft discarded — view/${VIEW}. [seq=41]`,
+};
+/** Framework receipt: nothing pending. 200, not 404. */
+const NO_DRAFT = {
+  success: true,
+  reset: false,
+  message: `No pending draft for view/${VIEW}.`,
+};
+/** Framework receipt: a runtime-only published row existed and is gone. */
+const PUBLISHED_DELETED = {
+  success: true,
+  reset: true,
+  seq: 42,
+  message: `Deleted view '${VIEW}' — it no longer exists. [seq=42]`,
+};
+/** Framework receipt: no published row. 200, not 404 — the answer #4479 quoted. */
+const NO_PUBLISHED = {
+  success: true,
+  reset: false,
+  message: `No view '${VIEW}' found — nothing to delete.`,
+};
+
+interface Call {
+  /** `'draft'` when the request carried `?state=draft`, else `'published'`. */
+  home: 'draft' | 'published';
+  method: string;
+  url: string;
+}
+
+interface Harness {
+  ds: any;
+  /** Every DELETE against `/meta/view/...`, in issue order. */
+  deletes: Call[];
+  /** Just the home of each DELETE, in issue order — the ordering pin. */
+  order: () => Array<'draft' | 'published'>;
+  /** Keys passed to `metadataCache.invalidate`, in order. */
+  invalidated: string[];
+  baseUrl: string;
+  fetchImpl: any;
+}
+
+/**
+ * Adapter whose two delete addresses answer independently.
+ *
+ * @param opts.draft      receipt (or Error/status) for `DELETE ...?state=draft`
+ * @param opts.published  receipt (or Error/status) for `DELETE ...` (active)
+ */
+function makeDS(opts: {
+  draft?: unknown | { failStatus: number };
+  published?: unknown | { failStatus: number };
+} = {}): Harness {
+  const deletes: Call[] = [];
+  const invalidated: string[] = [];
+  const baseUrl = 'http://test.local';
+
+  const json = (body: unknown, status = 200) =>
+    new Response(JSON.stringify(body), {
+      status,
+      headers: { 'Content-Type': 'application/json' },
+    });
+
+  const answer = (spec: unknown) => {
+    if (spec && typeof spec === 'object' && 'failStatus' in (spec as any)) {
+      const status = (spec as any).failStatus as number;
+      return json({ error: { message: 'boom', code: 'server_error' } }, status);
+    }
+    return json(spec);
+  };
+
+  const fetchImpl = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = String(input);
+    const method = init?.method ?? 'GET';
+    if (url.includes('/meta/view/')) {
+      if (method === 'DELETE') {
+        const home = url.includes('state=draft') ? 'draft' : 'published';
+        deletes.push({ home, method, url });
+        return answer(home === 'draft' ? opts.draft ?? NO_DRAFT : opts.published ?? NO_PUBLISHED);
+      }
+      return json({ error: 'not found' }, 404);
+    }
+    return json({ success: true, data: { capabilities: {}, routes: {} } });
+  });
+
+  const ds: any = new ObjectStackAdapter({ baseUrl, fetch: fetchImpl });
+  ds.connected = true;
+  ds.connectionState = 'connected';
+
+  ds.metadataCache = {
+    get: async (_key: string, loader: () => Promise<any>) => loader(),
+    invalidate: (key: string) => {
+      invalidated.push(key);
+    },
+    getCachedSync: () => undefined,
+    getStats: () => ({}),
+  };
+
+  // SDK transport stand-in. NOT a stub of the behaviour under test: it issues
+  // the same real request the shipped `client.meta.deleteItem` issues
+  // (`${baseUrl}/api/v1/meta/:type/:name`, DELETE) and unwraps the
+  // `{success, data}` envelope exactly as `unwrapResponse` does, so the
+  // published half is observed at the WIRE whichever transport carries it.
+  ds.client = {
+    meta: {
+      deleteItem: async (type: string, name: string) => {
+        const res = await fetchImpl(
+          `${baseUrl}/api/v1/meta/${encodeURIComponent(type)}/${encodeURIComponent(name)}`,
+          { method: 'DELETE' },
+        );
+        const body: any = await res.json();
+        if (!res.ok) {
+          throw Object.assign(new Error(body?.error?.message ?? 'request failed'), {
+            httpStatus: res.status,
+          });
+        }
+        if (body && typeof body.success === 'boolean' && 'data' in body) return body.data;
+        return body;
+      },
+      getItem: vi.fn(async () => {
+        throw Object.assign(new Error('Metadata item not found'), { httpStatus: 404 });
+      }),
+      saveItem: vi.fn(async () => ({ success: true })),
+      getItems: vi.fn(async () => ({ items: [] })),
+    },
+  };
+
+  return {
+    ds,
+    deletes,
+    order: () => deletes.map((c) => c.home),
+    invalidated,
+    baseUrl,
+    fetchImpl,
+  };
+}
+
+describe('deleteView removes every home the view has (#4479)', () => {
+  // ── Row 1: draft-only — the reported bug ────────────────────────────────
+  describe('draft-only view (the #4479 bug row)', () => {
+    it('deletes the draft home, so the view is actually gone', async () => {
+      const h = makeDS({ draft: DRAFT_DISCARDED, published: NO_PUBLISHED });
+
+      const receipt = await h.ds.deleteView('account', VIEW);
+
+      // The user-visible symptom first: before #4479 the only request issued
+      // was the unqualified one, the server answered `reset:false` /
+      // "nothing to delete", and this receipt came back `{deleted:false}`
+      // with the draft untouched and the tab back after reload.
+      expect(receipt.deleted).toBe(true);
+      // ...because the draft home was never addressed.
+      expect(h.order()).toContain('draft');
+    });
+
+    it('reports the draft home as the one that had the row', async () => {
+      const h = makeDS({ draft: DRAFT_DISCARDED, published: NO_PUBLISHED });
+
+      const receipt = await h.ds.deleteView('account', VIEW);
+
+      expect(receipt.draft?.removed).toBe(true);
+      expect(receipt.published?.removed).toBe(false);
+    });
+  });
+
+  // ── Row 2: published-only — correct before, must stay correct ───────────
+  describe('published-only view (correct before #4479)', () => {
+    it('still deletes the published home and still reports deleted', async () => {
+      const h = makeDS({ draft: NO_DRAFT, published: PUBLISHED_DELETED });
+
+      const receipt = await h.ds.deleteView('account', VIEW);
+
+      expect(h.order()).toContain('published');
+      // Unchanged from before #4479 — this half was never broken.
+      expect(receipt.deleted).toBe(true);
+    });
+
+    it('addresses both homes even when only one answers with a row', async () => {
+      const h = makeDS({ draft: NO_DRAFT, published: PUBLISHED_DELETED });
+
+      const receipt = await h.ds.deleteView('account', VIEW);
+
+      expect(h.order()).toEqual(['draft', 'published']);
+      expect(receipt.draft?.removed).toBe(false);
+      expect(receipt.published?.removed).toBe(true);
+    });
+  });
+
+  // ── Row 3: the pair — accidentally correct before; MUST NOT REGRESS ─────
+  describe('published + pending draft pair (must-not-change + the anti-mirror guard)', () => {
+    it('MUST NOT CHANGE: the published home is still deleted, so the tab still goes', async () => {
+      const h = makeDS({ draft: DRAFT_DISCARDED, published: PUBLISHED_DELETED });
+
+      const receipt = await h.ds.deleteView('account', VIEW);
+
+      // This is the assertion a naive draft-first mirror of #4139 would have
+      // broken: it would have discarded the draft and returned, leaving the
+      // published row serving the view and the tab present after reload.
+      expect(h.order()).toContain('published');
+      expect(receipt.deleted).toBe(true);
+    });
+
+    it('also discards the orphan draft, so a republish cannot resurrect the view', async () => {
+      const h = makeDS({ draft: DRAFT_DISCARDED, published: PUBLISHED_DELETED });
+
+      const receipt = await h.ds.deleteView('account', VIEW);
+
+      expect(h.order()).toEqual(['draft', 'published']);
+      expect(receipt.draft?.removed).toBe(true);
+      expect(receipt.published?.removed).toBe(true);
+    });
+
+    it('invalidates both view cache keys exactly once (#4363 rule, unchanged)', async () => {
+      const h = makeDS({ draft: DRAFT_DISCARDED, published: PUBLISHED_DELETED });
+
+      await h.ds.deleteView('account', VIEW);
+
+      // Two homes deleted, still ONE ordered pair: the #4363 rule is per
+      // WRITE METHOD, not per request.
+      expect(h.invalidated).toEqual([`view:account:${VIEW}`, 'view-overrides:account']);
+    });
+  });
+
+  // ── Row 4: neither home — the control ───────────────────────────────────
+  it('MUST NOT CHANGE: a view with no home at all reports deleted:false', async () => {
+    const h = makeDS({ draft: NO_DRAFT, published: NO_PUBLISHED });
+
+    const receipt = await h.ds.deleteView('account', VIEW);
+
+    // Both homes answer 200 `reset:false`. Nothing was removed and the
+    // receipt has never claimed otherwise — that answer is preserved.
+    expect(receipt.deleted).toBe(false);
+  });
+
+  // ── Ordering ────────────────────────────────────────────────────────────
+  it('addresses the draft home strictly before the published one', async () => {
+    const h = makeDS({ draft: DRAFT_DISCARDED, published: PUBLISHED_DELETED });
+
+    await h.ds.deleteView('account', VIEW);
+
+    expect(h.order()).toEqual(['draft', 'published']);
+    expect(h.deletes[0].url).toContain('state=draft');
+    expect(h.deletes[1].url).not.toContain('state=draft');
+  });
+
+  // ── One transport, one error contract ───────────────────────────────────
+  it('sends both deletes to the same `/api/v1/meta/view/:name` route', async () => {
+    const h = makeDS({ draft: DRAFT_DISCARDED, published: PUBLISHED_DELETED });
+
+    await h.ds.deleteView('account', VIEW);
+
+    const base = `${h.baseUrl}/api/v1/meta/view/${encodeURIComponent(VIEW)}`;
+    expect(h.deletes[0].url).toBe(`${base}?state=draft`);
+    expect(h.deletes[1].url).toBe(base);
+  });
+
+  // ── Failure paths — updateView's convention: throw, never degrade ───────
+  describe('partial failure', () => {
+    it('a failing draft delete throws and leaves the published home untouched', async () => {
+      const h = makeDS({ draft: { failStatus: 500 }, published: PUBLISHED_DELETED });
+
+      await expect(h.ds.deleteView('account', VIEW)).rejects.toThrow();
+
+      // The whole reason the ruling put the draft FIRST: a mid-operation
+      // failure must leave the published overlay serving the view, so the
+      // user retries a delete rather than being left with the draft-only
+      // shape that is this card's original bug.
+      expect(h.order()).toEqual(['draft']);
+    });
+
+    it('a failing published delete throws rather than reporting deleted:true', async () => {
+      const h = makeDS({ draft: DRAFT_DISCARDED, published: { failStatus: 500 } });
+
+      await expect(h.ds.deleteView('account', VIEW)).rejects.toThrow();
+
+      expect(h.order()).toEqual(['draft', 'published']);
+    });
+
+    it('the published-half failure carries the partial outcome, never rounds it to true', async () => {
+      const h = makeDS({ draft: DRAFT_DISCARDED, published: { failStatus: 500 } });
+
+      const err: any = await h.ds.deleteView('account', VIEW).catch((e: any) => e);
+
+      // "draft gone, overlay left" is exactly what the old
+      // `{ deleted: boolean }` could not express.
+      expect(err.outcome?.deleted).toBe(false);
+      expect(err.outcome?.draft?.removed).toBe(true);
+      expect(err.outcome?.published?.removed).toBe(false);
+      expect(err.cause).toBeDefined();
+    });
+
+    it('still invalidates the view cache keys when a half fails', async () => {
+      const h = makeDS({ draft: DRAFT_DISCARDED, published: { failStatus: 500 } });
+
+      await h.ds.deleteView('account', VIEW).catch(() => undefined);
+
+      // The draft row IS gone, so a cache still holding it is stale for the
+      // full TTL. #4363's asymmetry decides it: an unnecessary invalidation
+      // costs one refetch, a missed one costs five minutes of stale overrides.
+      expect(h.invalidated).toEqual([`view:account:${VIEW}`, 'view-overrides:account']);
+    });
+  });
+
+  // ── discardRuntimeDraft stays a DIFFERENT operation ─────────────────────
+  it('stays distinct from Discard draft, which touches only the draft home', async () => {
+    // `discardRuntimeDraft` (app-shell `runtime-metadata-persistence.ts`) is
+    // documented as "the published overlay is untouched" and is exactly this
+    // one call. Driven here through the same primitive rather than imported,
+    // because app-shell is downstream of this package — the point is that the
+    // two operations issue DIFFERENT request sets against the same wire.
+    const h = makeDS({ draft: DRAFT_DISCARDED, published: PUBLISHED_DELETED });
+
+    await new MetadataClient({ baseUrl: h.baseUrl, fetch: h.fetchImpl }).reset('view', VIEW, {
+      state: 'draft',
+    });
+    expect(h.order()).toEqual(['draft']);
+
+    // Same wire, same view: Delete view addresses BOTH homes. If these two
+    // ever issue the same request set, one of the operations has been lost.
+    const fresh = makeDS({ draft: DRAFT_DISCARDED, published: PUBLISHED_DELETED });
+    await fresh.ds.deleteView('account', VIEW);
+    expect(fresh.order()).toEqual(['draft', 'published']);
+  });
+});

package/src/deleteViewContract.types.test.ts

@@ -0,0 +1,246 @@
+/**
+ * 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.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import type { DataSource, DeleteViewResult, ViewHomeDeleteOutcome } from '@object-ui/types';
+import {
+  ObjectStackAdapter,
+  type DeleteViewResult as AdapterDeleteViewResult,
+  type ViewHomeDeleteOutcome as AdapterViewHomeDeleteOutcome,
+} from './index';
+
+/**
+ * The shared `DataSource` contract carries `deleteView`'s per-home outcomes
+ * (#4564).
+ *
+ * #4479 / PR #4562 widened THIS adapter's `deleteView` to return
+ * `DeleteViewResult { deleted, draft?, published? }`, but the shared interface
+ * in `@object-ui/types` still declared the narrow `{ deleted: boolean }`. The
+ * adapter's wider return is assignable to the narrower declaration, so nothing
+ * failed to compile — which is exactly what made the gap invisible: a consumer
+ * reaching the adapter THROUGH `DataSource` was handed a type that had already
+ * thrown the per-home outcomes away. The one real call site today (app-shell's
+ * `ObjectView` delete handler) reads nothing off the receipt, so the loss was
+ * latent rather than broken.
+ *
+ * #4564's ruling moved the canonical shapes DOWN to `@object-ui/types` beside
+ * the interface (the dependency runs data-objectstack -> types, so the shapes
+ * could not be imported upward), widened `DataSource.deleteView?`'s declared
+ * return to `DeleteViewResult`, and left this package re-exporting both names
+ * so every existing importer keeps compiling.
+ *
+ * ## Where these pins get their colour
+ *
+ * Most of this file is COMPILE-time. That is not a weaker pin, it is the only
+ * pin that can observe this defect: the bug was never a wrong value at runtime,
+ * it was a declaration that could not describe the value. `vitest` transpiles
+ * with esbuild and erases types, so the runtime case below passed just as
+ * happily against the narrow declaration — its `receipt.draft` read was a
+ * `tsc` error and a green test at the same time. The colour therefore comes
+ * from `pnpm --filter @object-ui/data-objectstack type-check`, and this
+ * package's `tsconfig.json` includes its whole `src/**` (tests included), so
+ * these assertions are checked there and by CI's Type Check job with no
+ * separate `tsconfig.typetests.json` — the same property `queryDataset.test.ts`
+ * and `spec-symbol-batch6.test.ts` document and rely on.
+ *
+ * ## The discrimination control
+ *
+ * `NarrowLegacyResult` below is `deleteView`'s declared return BEFORE #4564,
+ * kept as a live control rather than described in prose. Every "the contract
+ * carries the per-home outcomes" assertion is paired with the control failing
+ * to carry them. Undo the move and the paired assertions go red together,
+ * which is what stops this file from degrading into a restatement of whatever
+ * the interface happens to say.
+ */
+
+const VIEW = 'account.my_pipeline';
+
+/** Framework receipt: a draft row existed and was discarded. */
+const DRAFT_DISCARDED = {
+  success: true,
+  reset: true,
+  seq: 41,
+  message: `Draft discarded — view/${VIEW}. [seq=41]`,
+};
+
+/** Framework receipt: no published row. A 200 carrying `reset:false`, not a 404. */
+const NO_PUBLISHED = {
+  success: true,
+  reset: false,
+  message: `No view '${VIEW}' found — nothing to delete.`,
+};
+
+/**
+ * The smallest adapter that can answer both view-delete addresses.
+ *
+ * Deliberately NOT a second copy of `deleteView.homes.test.ts`'s harness: that
+ * file owns the behaviour (15 pins over both homes, the ordering, the failure
+ * paths) and stays untouched. This one exists only to drive one call through a
+ * `DataSource`-typed handle, so the per-home read below is served by the shared
+ * declaration and by nothing else.
+ */
+function makeAdapter(): ObjectStackAdapter {
+  const baseUrl = 'http://test.local';
+  const json = (body: unknown) =>
+    new Response(JSON.stringify(body), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    });
+
+  const fetchImpl = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = String(input);
+    if (url.includes('/meta/view/') && (init?.method ?? 'GET') === 'DELETE') {
+      return json(url.includes('state=draft') ? DRAFT_DISCARDED : NO_PUBLISHED);
+    }
+    return json({ success: true, data: { capabilities: {}, routes: {} } });
+  });
+
+  const adapter = new ObjectStackAdapter({ baseUrl, fetch: fetchImpl });
+  const poke = adapter as any;
+  poke.connected = true;
+  poke.connectionState = 'connected';
+  poke.metadataCache = {
+    get: async (_key: string, loader: () => Promise<any>) => loader(),
+    invalidate: () => undefined,
+    getCachedSync: () => undefined,
+    getStats: () => ({}),
+  };
+  return adapter;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Compile-time vocabulary — the repo's idiom (queryDataset.test.ts).          */
+/* -------------------------------------------------------------------------- */
+
+type Assert<T extends true> = T;
+type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
+  ? true
+  : false;
+type HasKey<T, K extends PropertyKey> = K extends keyof T ? true : false;
+
+/** The shared contract's declared return, read off the interface itself. */
+type ContractDeleteView = NonNullable<DataSource['deleteView']>;
+type ContractReturn = Awaited<ReturnType<ContractDeleteView>>;
+
+/**
+ * `DataSource.deleteView`'s declared return BEFORE #4564 — the control.
+ * Kept as a type, not a comment, so "the contract used to lose the per-home
+ * outcomes" is an assertion the compiler re-checks on every run.
+ */
+interface NarrowLegacyResult {
+  deleted: boolean;
+}
+
+describe('DataSource.deleteView declares the per-home outcomes (#4564)', () => {
+  it('the shared contract returns the canonical DeleteViewResult, not a restatement', () => {
+    // `Equal` rather than a two-way `extends`: a structurally overlapping
+    // re-declaration in `types` would satisfy mutual assignability while
+    // drifting, and a hand copy is precisely what the one-resolver rule and
+    // this card's ruling rejected in favour of moving the declaration.
+    type _IsTheCanonicalShape = Assert<Equal<ContractReturn, DeleteViewResult>>;
+
+    expect(true).toBe(true);
+  });
+
+  it('carries `draft` and `published`, where the pre-#4564 declaration carried neither', () => {
+    type _CarriesDraft = Assert<Equal<HasKey<ContractReturn, 'draft'>, true>>;
+    type _CarriesPublished = Assert<Equal<HasKey<ContractReturn, 'published'>, true>>;
+
+    // The control, and the whole reason this file is a pin rather than an echo:
+    // the shape the interface used to declare cannot answer either read. If the
+    // move is reverted, the two assertions above go red and these two stay
+    // green — the difference between them IS #4564's delta.
+    type _ControlHasNoDraft = Assert<Equal<HasKey<NarrowLegacyResult, 'draft'>, false>>;
+    type _ControlHasNoPublished = Assert<Equal<HasKey<NarrowLegacyResult, 'published'>, false>>;
+    type _ContractIsNotTheNarrowShape = Assert<
+      Equal<Equal<ContractReturn, NarrowLegacyResult>, false>
+    >;
+
+    expect(true).toBe(true);
+  });
+
+  it('types the per-home outcomes as ViewHomeDeleteOutcome, optional on both homes', () => {
+    type _DraftIsTheOutcome = Assert<Equal<ContractReturn['draft'], ViewHomeDeleteOutcome | undefined>>;
+    type _PublishedIsTheOutcome = Assert<
+      Equal<ContractReturn['published'], ViewHomeDeleteOutcome | undefined>
+    >;
+    // `deleted` is unchanged — the growth is additive, so a consumer reading
+    // only `deleted` is untouched by the widening.
+    type _DeletedUnchanged = Assert<Equal<ContractReturn['deleted'], boolean>>;
+
+    expect(true).toBe(true);
+  });
+
+  it('MUST NOT CHANGE: deleteView stays OPTIONAL, with the same two parameters', () => {
+    // The widening is to the RETURN only. An adapter that never implemented
+    // `deleteView` must stay a legal `DataSource`.
+    type _StillOptional = Assert<undefined extends DataSource['deleteView'] ? true : false>;
+    type _SameParameters = Assert<Equal<Parameters<ContractDeleteView>, [string, string]>>;
+
+    expect(true).toBe(true);
+  });
+});
+
+describe('the data-objectstack spellings survive the move (#4564)', () => {
+  it('re-exports both names as the SAME declaration, not a structural twin', () => {
+    // The re-export contract: every importer that PR #4562 left pointing at
+    // `@object-ui/data-objectstack` keeps compiling, and keeps getting the type
+    // the shared interface now speaks. `Equal` is the assertion that matters —
+    // two identical-looking declarations are mutually assignable, so only
+    // identity can tell a re-export from a copy that will drift.
+    type _ResultIsTheTypesSpelling = Assert<Equal<AdapterDeleteViewResult, DeleteViewResult>>;
+    type _OutcomeIsTheTypesSpelling = Assert<
+      Equal<AdapterViewHomeDeleteOutcome, ViewHomeDeleteOutcome>
+    >;
+
+    expect(true).toBe(true);
+  });
+
+  it('the adapter method still satisfies the widened contract', () => {
+    const adapter = makeAdapter();
+
+    // Explicit, because `class ObjectStackAdapter implements DataSource` would
+    // have gone on compiling with the NARROW declaration too — a wider return
+    // is assignable to a narrower one, which is how the gap survived #4562's
+    // review in the first place. This states the direction the card cares
+    // about instead of inheriting it from the class heritage clause.
+    const deleteView = adapter.deleteView.bind(adapter) satisfies ContractDeleteView;
+    expect(typeof deleteView).toBe('function');
+
+    type _AdapterAssignableToContract = Assert<
+      ObjectStackAdapter['deleteView'] extends ContractDeleteView ? true : false
+    >;
+    // ...and no longer merely assignable: the two returns are now one type, so
+    // the adapter cannot widen further without the contract following it.
+    type _ReturnsAreOneType = Assert<
+      Equal<Awaited<ReturnType<ObjectStackAdapter['deleteView']>>, ContractReturn>
+    >;
+
+    expect(true).toBe(true);
+  });
+});
+
+describe('a consumer holding only the shared DataSource (#4564)', () => {
+  it('reads the per-home outcomes the adapter actually returns', async () => {
+    const adapter = makeAdapter();
+
+    // The narrowing that makes this a #4564 pin rather than a duplicate of
+    // `deleteView.homes.test.ts`: the receipt below is typed by `DataSource`,
+    // not by `ObjectStackAdapter`. Before the move this assignment compiled
+    // just as well and threw the per-home outcomes away on the way through.
+    const ds: DataSource = adapter;
+
+    const receipt = await ds.deleteView!('account', VIEW);
+
+    // Draft-only view: the draft home held the row, the published one did not.
+    expect(receipt.deleted).toBe(true);
+    expect(receipt.draft?.removed).toBe(true);
+    expect(receipt.published?.removed).toBe(false);
+    expect(receipt.draft?.message).toContain('Draft discarded');
+  });
+});