@cosmicdrift/kumiko-bundled-features 0.224.2 → 0.226.0

package/src/cap-overview/web/__tests__/cap-cards-panel.test.tsx

@@ -0,0 +1,244 @@
+// @runtime test
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+import type { DispatcherError } from "@cosmicdrift/kumiko-headless";
+import {
+  createStaticLocaleResolver,
+  type ExtensionSectionProps,
+  LocaleProvider,
+  PrimitivesProvider,
+} from "@cosmicdrift/kumiko-renderer";
+import { defaultPrimitives } from "@cosmicdrift/kumiko-renderer-web";
+import { render, screen } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { CapOverviewQueries } from "../../constants";
+import type { CapUsageTone, CapUsageWithMeta } from "../../types";
+import { CapCardsPanel } from "../cap-cards-panel";
+
+type CapsUsageResponse = { readonly rows: readonly CapUsageWithMeta[] };
+
+type QueryState = {
+  readonly data: CapsUsageResponse | null;
+  readonly loading: boolean;
+  readonly error: DispatcherError | null;
+};
+
+let queryState: QueryState = { data: { rows: [] }, loading: false, error: null };
+
+const useQuerySpy = mock((_type: string, _params: unknown) => ({
+  ...queryState,
+  refetch: mock(async () => {}),
+}));
+
+const actualRenderer = await import("@cosmicdrift/kumiko-renderer");
+mock.module("@cosmicdrift/kumiko-renderer", () => ({
+  ...actualRenderer,
+  useQuery: useQuerySpy,
+}));
+
+// The real StatusBadge bakes `tone` into a computed Tailwind class string and
+// exposes it nowhere in the DOM — asserting TONE_TO_STATUS through it would
+// mean matching class substrings. Surface the prop as data-tone instead.
+const actualRendererWeb = await import("@cosmicdrift/kumiko-renderer-web");
+mock.module("@cosmicdrift/kumiko-renderer-web", () => ({
+  ...actualRendererWeb,
+  StatusBadge: ({
+    tone,
+    children,
+  }: {
+    readonly tone: string;
+    readonly children: ReactNode;
+  }): ReactNode => <span data-tone={tone}>{children}</span>,
+}));
+
+function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
+  return (
+    <LocaleProvider resolver={createStaticLocaleResolver()}>
+      <PrimitivesProvider value={defaultPrimitives}>{children}</PrimitivesProvider>
+    </LocaleProvider>
+  );
+}
+
+function renderPanel(filterParams: ExtensionSectionProps["filterParams"]): void {
+  render(
+    <Wrapper>
+      <CapCardsPanel
+        entityName="cap-overview-dashboard"
+        entityId={null}
+        filterParams={filterParams}
+      />
+    </Wrapper>,
+  );
+}
+
+function capRow(overrides: Partial<CapUsageWithMeta> = {}): CapUsageWithMeta {
+  return {
+    id: "cap-1",
+    label: "cap.label",
+    tone: "default",
+    percent: 0,
+    used: 0,
+    limit: 100,
+    fraction: 0,
+    ...overrides,
+  };
+}
+
+function nullCapRow(overrides: Partial<CapUsageWithMeta> = {}): CapUsageWithMeta {
+  return {
+    id: "cap-null",
+    label: "cap.label.null",
+    tone: "default",
+    percent: null,
+    used: null,
+    limit: 100,
+    fraction: 0,
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  queryState = { data: { rows: [] }, loading: false, error: null };
+  useQuerySpy.mockClear();
+});
+
+describe("CapCardsPanel", () => {
+  test("renders one card per row, with the row's label and used/limit value", () => {
+    queryState = {
+      data: {
+        rows: [
+          capRow({ id: "c1", label: "Storage", used: 3, limit: 10 }),
+          capRow({ id: "c2", label: "Seats", used: 7, limit: 20 }),
+        ],
+      },
+      loading: false,
+      error: null,
+    };
+
+    renderPanel(undefined);
+
+    expect(screen.getAllByTestId("cap-card")).toHaveLength(2);
+    expect(screen.getByText("Storage")).toBeTruthy();
+    expect(screen.getByText("Seats")).toBeTruthy();
+    expect(screen.getByText("3 / 10")).toBeTruthy();
+    expect(screen.getByText("7 / 20")).toBeTruthy();
+  });
+
+  test("maps the default tone to the muted StatusBadge tone", () => {
+    queryState = {
+      data: { rows: [capRow({ tone: "default", percent: 12 })] },
+      loading: false,
+      error: null,
+    };
+
+    renderPanel(undefined);
+
+    expect(screen.getByText("12%").getAttribute("data-tone")).toBe("muted");
+  });
+
+  test("maps the warn tone to the warn StatusBadge tone", () => {
+    queryState = {
+      data: { rows: [capRow({ tone: "warn", percent: 80 })] },
+      loading: false,
+      error: null,
+    };
+
+    renderPanel(undefined);
+
+    expect(screen.getByText("80%").getAttribute("data-tone")).toBe("warn");
+  });
+
+  test("maps the danger tone to the critical StatusBadge tone", () => {
+    const tone: CapUsageTone = "danger";
+    queryState = { data: { rows: [capRow({ tone, percent: 99 })] }, loading: false, error: null };
+
+    renderPanel(undefined);
+
+    expect(screen.getByText("99%").getAttribute("data-tone")).toBe("critical");
+  });
+
+  test("empty rows without loading show the empty state and no cards", () => {
+    queryState = { data: { rows: [] }, loading: false, error: null };
+
+    renderPanel(undefined);
+
+    expect(screen.getByTestId("cap-cards-panel-empty")).toBeTruthy();
+    expect(screen.queryAllByTestId("cap-card")).toHaveLength(0);
+  });
+
+  test("a query error shows the error banner with the message and no cards", () => {
+    queryState = {
+      data: null,
+      loading: false,
+      error: {
+        code: "internal",
+        httpStatus: 500,
+        i18nKey: "kumiko.error.internal",
+        message: "caps usage failed",
+      },
+    };
+
+    renderPanel(undefined);
+
+    expect(screen.getByTestId("cap-cards-panel-error").textContent).toContain("caps usage failed");
+    expect(screen.queryAllByTestId("cap-card")).toHaveLength(0);
+  });
+
+  test("a string tenantId in filterParams is passed through to useQuery", () => {
+    renderPanel({ tenantId: "t-42" });
+
+    expect(useQuerySpy).toHaveBeenCalledWith(CapOverviewQueries.capsUsage, { tenantId: "t-42" });
+  });
+
+  test("missing or non-string tenantId in filterParams omits the tenantId key", () => {
+    renderPanel(undefined);
+    const [, undefinedFilterArgs] = useQuerySpy.mock.calls[0] as [string, Record<string, unknown>];
+    expect("tenantId" in undefinedFilterArgs).toBe(false);
+
+    useQuerySpy.mockClear();
+    renderPanel({ tenantId: 123 });
+    const [, numericTenantIdArgs] = useQuerySpy.mock.calls[0] as [string, Record<string, unknown>];
+    expect("tenantId" in numericTenantIdArgs).toBe(false);
+  });
+
+  test("a card with used: null shows the em-dash value and not-measured text, no bar or percent badge", () => {
+    queryState = {
+      data: { rows: [nullCapRow()] },
+      loading: false,
+      error: null,
+    };
+
+    renderPanel(undefined);
+
+    expect(screen.getByTestId("cap-card").textContent).toContain("—");
+    expect(screen.getByTestId("cap-usage-not-measured")).toBeTruthy();
+    expect(screen.queryByTestId("cap-usage-bar")).toBeNull();
+    expect(screen.queryByText("null%")).toBeNull();
+    expect(screen.queryByText("0%")).toBeNull();
+  });
+
+  test("a null-usage card and a measured card in the same panel each render their own state", () => {
+    queryState = {
+      data: {
+        rows: [capRow({ id: "c1", label: "Storage", used: 3, limit: 10 }), nullCapRow()],
+      },
+      loading: false,
+      error: null,
+    };
+
+    renderPanel(undefined);
+
+    expect(screen.getAllByTestId("cap-card")).toHaveLength(2);
+    expect(screen.getByText("3 / 10")).toBeTruthy();
+    expect(screen.getByTestId("cap-usage-not-measured")).toBeTruthy();
+    expect(screen.getAllByTestId("cap-usage-bar")).toHaveLength(1);
+  });
+
+  test("loading with empty rows shows the loading text instead of the empty state", () => {
+    queryState = { data: null, loading: true, error: null };
+
+    renderPanel(undefined);
+
+    expect(screen.getByText("cap-overview.cards.loading")).toBeTruthy();
+    expect(screen.queryByTestId("cap-cards-panel-empty")).toBeNull();
+  });
+});

package/src/cap-overview/web/__tests__/cap-usage-bar.test.tsx

@@ -0,0 +1,76 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createStaticLocaleResolver,
+  LocaleProvider,
+  PrimitivesProvider,
+} from "@cosmicdrift/kumiko-renderer";
+import { defaultPrimitives } from "@cosmicdrift/kumiko-renderer-web";
+import { render, screen } from "@testing-library/react";
+import type { ReactNode } from "react";
+import type { CapUsage } from "../../types";
+import { CapUsageBar } from "../cap-usage-bar";
+
+function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
+  return (
+    <LocaleProvider resolver={createStaticLocaleResolver()}>
+      <PrimitivesProvider value={defaultPrimitives}>{children}</PrimitivesProvider>
+    </LocaleProvider>
+  );
+}
+
+function fillClass(): string | undefined {
+  return screen.getByTestId("cap-usage-bar").firstElementChild?.className;
+}
+
+describe("CapUsageBar", () => {
+  test("renders the not-measured text instead of a bar when used is null", () => {
+    const usage: CapUsage = { used: null, limit: 100, fraction: 0 };
+    render(
+      <Wrapper>
+        <CapUsageBar usage={usage} showLabel={false} />
+      </Wrapper>,
+    );
+
+    expect(screen.queryByTestId("cap-usage-bar")).toBeNull();
+    expect(screen.getByTestId("cap-usage-not-measured").textContent).toBe(
+      "cap-overview.notMeasured",
+    );
+  });
+
+  test("renders the danger fill class when usage is at or over the limit", () => {
+    const usage: CapUsage = { used: 120, limit: 100, fraction: 1.2 };
+    render(
+      <Wrapper>
+        <CapUsageBar usage={usage} showLabel={false} />
+      </Wrapper>,
+    );
+
+    expect(fillClass()).toContain("bg-status-critical");
+    expect(fillClass()).not.toContain("bg-primary");
+  });
+
+  test("renders the default fill class when usage is well under the limit", () => {
+    const usage: CapUsage = { used: 4, limit: 100, fraction: 0.04 };
+    render(
+      <Wrapper>
+        <CapUsageBar usage={usage} showLabel={false} />
+      </Wrapper>,
+    );
+
+    expect(fillClass()).toContain("bg-primary");
+    expect(fillClass()).not.toContain("bg-status-critical");
+  });
+
+  test("renders the warn fill class when usage is in the warn zone", () => {
+    const usage: CapUsage = { used: 85, limit: 100, fraction: 0.85 };
+    render(
+      <Wrapper>
+        <CapUsageBar usage={usage} showLabel={false} />
+      </Wrapper>,
+    );
+
+    expect(fillClass()).toContain("bg-status-warn");
+    expect(fillClass()).not.toContain("bg-primary");
+    expect(fillClass()).not.toContain("bg-status-critical");
+  });
+});

package/src/cap-overview/web/cap-cards-panel.tsx

@@ -0,0 +1,109 @@
+// @runtime client
+import type { ExtensionSectionProps } from "@cosmicdrift/kumiko-renderer";
+import { usePrimitives, useQuery, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import {
+  EmptyState,
+  StatCard,
+  StatusBadge,
+  type StatusTone,
+} from "@cosmicdrift/kumiko-renderer-web";
+import { Database, FileText, Gauge, Hash, Mail, Users } from "lucide-react";
+import type { ComponentType, ReactNode } from "react";
+import { CapOverviewQueries } from "../constants";
+import type { CapIconKey, CapUsageTone, CapUsageWithMeta } from "../types";
+import { CapUsageBar } from "./cap-usage-bar";
+
+type CapsUsageResponse = { readonly rows: readonly CapUsageWithMeta[] };
+
+// caps:usage's wire tone stays "default"/"warn"/"danger" (matches the
+// server-side thresholds literally); mapped here to the renderer's actual
+// StatusTone vocabulary instead of inventing new CSS ("danger" has no
+// StatusBadge tone equivalent — "critical" is the closer semantic fit).
+const TONE_TO_STATUS: Record<CapUsageTone, StatusTone> = {
+  default: "muted",
+  warn: "warn",
+  danger: "critical",
+};
+
+// Matches CapIconKey (types.ts) 1:1 — extend both together.
+const CAP_ICONS: Record<CapIconKey, ComponentType<{ className?: string }>> = {
+  file: FileText,
+  hash: Hash,
+  database: Database,
+  users: Users,
+  mail: Mail,
+  gauge: Gauge,
+};
+
+// Narrows `percent` to non-null alongside `used` — the query handler only
+// ever sets both or neither, but the type doesn't encode that link.
+function isMeasured(
+  cap: CapUsageWithMeta,
+): cap is CapUsageWithMeta & { used: number; percent: number } {
+  return cap.used !== null;
+}
+
+export function CapCardsPanel({ filterParams }: ExtensionSectionProps): ReactNode {
+  const t = useTranslation();
+  const { Banner } = usePrimitives();
+  const tenantId =
+    typeof filterParams?.["tenantId"] === "string" ? filterParams["tenantId"] : undefined;
+  const query = useQuery<CapsUsageResponse | null>(CapOverviewQueries.capsUsage, {
+    ...(tenantId !== undefined && { tenantId }),
+  });
+
+  if (query.error !== null) {
+    return (
+      <Banner variant="error" testId="cap-cards-panel-error">
+        {query.error.message}
+      </Banner>
+    );
+  }
+
+  const rows = query.data?.rows ?? [];
+
+  if (!query.loading && rows.length === 0) {
+    return <EmptyState title={t("cap-overview.cards.empty")} testId="cap-cards-panel-empty" />;
+  }
+
+  return (
+    <div
+      // Arbitrary bracket values (grid-cols-[repeat(...)]) never compiled:
+      // styles.css's Tailwind v4 @source scan only covers renderer-web/src,
+      // renderer/src and samples/**/src (see its comment) — bundled-features
+      // isn't scanned, so a class unique to this file has no generated rule
+      // and silently no-ops (the grid fell back to one implicit column,
+      // stacking every card full-width). Reusing the exact classes
+      // dashboard-body.tsx's own panel grid already uses guarantees the
+      // rule exists, since that file IS in the scanned surface.
+      className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4"
+      data-testid="cap-cards-panel"
+    >
+      {query.loading && rows.length === 0 && (
+        <div className="text-sm text-muted-foreground">{t("cap-overview.cards.loading")}</div>
+      )}
+      {rows.map((cap) => {
+        const Icon = cap.icon !== undefined ? CAP_ICONS[cap.icon] : undefined;
+        return (
+          <StatCard
+            key={cap.id}
+            icon={Icon !== undefined ? <Icon className="size-4" /> : undefined}
+            label={t(cap.label)}
+            value={isMeasured(cap) ? `${cap.used} / ${cap.limit}` : "—"}
+            {...(cap.accentColor !== undefined && { accentColor: cap.accentColor })}
+            testId="cap-card"
+          >
+            <div className="flex flex-col gap-2">
+              {isMeasured(cap) && (
+                <div className="flex items-center justify-between gap-2">
+                  <StatusBadge tone={TONE_TO_STATUS[cap.tone]}>{`${cap.percent}%`}</StatusBadge>
+                </div>
+              )}
+              <CapUsageBar usage={cap} showLabel={false} />
+            </div>
+          </StatCard>
+        );
+      })}
+    </div>
+  );
+}

package/src/cap-overview/web/cap-usage-bar.tsx

@@ -0,0 +1,47 @@
+// @runtime client
+import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import type { CapUsage } from "../types";
+import { computeTone } from "../usage-math";
+
+export function CapUsageBar({
+  usage,
+  showLabel = true,
+}: {
+  readonly usage: CapUsage;
+  // The cap-cards-panel StatCard already shows used/limit as its headline
+  // value — the bar's own label would just repeat it there.
+  readonly showLabel?: boolean;
+}): ReactNode {
+  const { Progress, Text, Banner } = usePrimitives();
+  const t = useTranslation();
+
+  if (usage.used === null) {
+    return (
+      <Text variant="small" testId="cap-usage-not-measured">
+        {t("cap-overview.notMeasured")}
+      </Text>
+    );
+  }
+
+  return (
+    <div className="flex flex-col gap-1">
+      {Progress ? (
+        <Progress
+          value={usage.fraction}
+          tone={computeTone(usage.fraction)}
+          testId="cap-usage-bar"
+        />
+      ) : (
+        // Progress is typed optional only so partial CorePrimitives test
+        // doubles keep compiling — production always registers it via
+        // defaultPrimitives. If it's ever missing, say so instead of
+        // silently dropping the bar (it's the requested content, not decoration).
+        <Banner variant="error" testId="cap-usage-bar-missing-primitive">
+          {t("cap-overview.errors.progressPrimitiveMissing")}
+        </Banner>
+      )}
+      {showLabel && <Text variant="small">{`${usage.used} / ${usage.limit}`}</Text>}
+    </div>
+  );
+}

package/src/cap-overview/web/cap-usage-cell.tsx

@@ -0,0 +1,20 @@
+// @runtime client
+import type { ColumnRendererProps } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import type { CapUsage } from "../types";
+import { CapUsageBar } from "./cap-usage-bar";
+
+function isCapUsage(value: unknown): value is CapUsage {
+  if (typeof value !== "object" || value === null) return false;
+  const used = (value as { used?: unknown }).used;
+  return (
+    (typeof used === "number" || used === null) &&
+    typeof (value as { limit?: unknown }).limit === "number" &&
+    typeof (value as { fraction?: unknown }).fraction === "number"
+  );
+}
+
+export function CapUsageCell({ value }: ColumnRendererProps): ReactNode {
+  if (!isCapUsage(value)) return null;
+  return <CapUsageBar usage={value} />;
+}

package/src/cap-overview/web/client-plugin.tsx

@@ -0,0 +1,27 @@
+// @runtime client
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import {
+  CAP_CARDS_PANEL_COMPONENT,
+  CAP_OVERVIEW_FEATURE,
+  CAP_USAGE_CELL_COMPONENT,
+} from "../constants";
+import { CapCardsPanel } from "./cap-cards-panel";
+import { CapUsageCell } from "./cap-usage-cell";
+
+export type CapOverviewClientOptions = {
+  readonly translations?: TranslationsByLocale;
+};
+
+export function capOverviewClient(options?: CapOverviewClientOptions): ClientFeatureDefinition {
+  return {
+    name: CAP_OVERVIEW_FEATURE,
+    columnRenderers: {
+      [CAP_USAGE_CELL_COMPONENT]: CapUsageCell,
+    },
+    extensionSectionComponents: {
+      [CAP_CARDS_PANEL_COMPONENT]: CapCardsPanel,
+    },
+    ...(options?.translations !== undefined && { translations: options.translations }),
+  };
+}

package/src/cap-overview/web/index.ts

@@ -0,0 +1,10 @@
+// @runtime client
+// Public exports for the browser side of the cap-overview feature.
+// Consumed via `@cosmicdrift/kumiko-bundled-features/cap-overview/web` —
+// the server side (createCapOverviewFeature) lives under
+// `@cosmicdrift/kumiko-bundled-features/cap-overview` and has no React deps.
+
+export { CapCardsPanel } from "./cap-cards-panel";
+export { CapUsageBar } from "./cap-usage-bar";
+export { CapUsageCell } from "./cap-usage-cell";
+export { type CapOverviewClientOptions, capOverviewClient } from "./client-plugin";

package/src/form-draft/__tests__/cleanup.integration.test.ts

@@ -244,12 +244,17 @@ describe("form-draft cleanup job — FileRef release (#1915)", () => {
 
     await dispatchCleanup();
 
-    await waitFor(async () => {
-      expect(await draftExists("wizard:stale-with-photo")).toBe(false);
+    // Draft deletion and FileRef release are two separate awaited phases in
+    // cleanup.job.ts — the whole batch is deleted first, then released row
+    // by row. Waiting on draftExists only proves the delete phase finished,
+    // not the (real DB + provider) release; wait on the actual release
+    // effect instead, or this assertion races the still-in-flight release.
+    await waitFor(() => {
+      expect(providerA.keys()).not.toContain(key);
     });
+    expect(await draftExists("wizard:stale-with-photo")).toBe(false);
     expect(await draftExists("wizard:stale-no-photo")).toBe(false);
     expect(await draftExists("wizard:fresh")).toBe(true);
-    expect(providerA.keys()).not.toContain(key);
   });
 
   test("resolves each stale row's own tenant provider — never the job's SYSTEM_TENANT_ID run-tenant, never another row's tenant", async () => {
@@ -267,15 +272,18 @@ describe("form-draft cleanup job — FileRef release (#1915)", () => {
 
     await dispatchCleanup();
 
-    await waitFor(async () => {
-      expect(await draftExists("wizard:tenant-a-stale")).toBe(false);
+    // Same two-phase timing as the single-tenant release test above: wait on
+    // each provider's actual release, not on draft deletion (which finishes
+    // for the whole batch before either row's release even starts).
+    await waitFor(() => {
+      expect(providerA.keys()).not.toContain(keyA);
     });
-    await waitFor(async () => {
-      expect(await draftExists("wizard:tenant-b-stale")).toBe(false);
+    await waitFor(() => {
+      expect(providerB.keys()).not.toContain(keyB);
     });
 
-    expect(providerA.keys()).not.toContain(keyA);
-    expect(providerB.keys()).not.toContain(keyB);
+    expect(await draftExists("wizard:tenant-a-stale")).toBe(false);
+    expect(await draftExists("wizard:tenant-b-stale")).toBe(false);
     // Cross-tenant guard: neither key ever lands in the other tenant's provider.
     expect(providerA.keys()).not.toContain(keyB);
     expect(providerB.keys()).not.toContain(keyA);
@@ -286,15 +294,28 @@ describe("form-draft cleanup job — FileRef release (#1915)", () => {
     await providerA.write(forgedKey, new Uint8Array([9, 9, 9]), "image/jpeg");
     // Deliberately no seedFileRef — the stale draft's `values` claims a
     // storageKey its owner never actually uploaded.
-
     await saveDraft("wizard:stale-forged", { photo: fileRefPointer(forgedKey) });
-    await backdate("wizard:stale-forged", 31);
+    await backdate("wizard:stale-forged", 40);
+
+    // Release sentinel: a real, legitimately-owned FileRef backdated less
+    // than the forged row, so selectStaleDraftsBatch's oldest-first order
+    // processes the forged row first. Releases are awaited sequentially in
+    // order within one job run, so observing the sentinel's release proves
+    // the forged row's (earlier) release turn already ran and correctly did
+    // nothing — a plain draftExists wait can't prove that, only that the
+    // delete phase (which precedes all releases) has finished.
+    const sentinelKey = "tenant-a/vehicle/forged-sentinel.jpg";
+    await providerA.write(sentinelKey, new Uint8Array([7]), "image/jpeg");
+    await seedFileRef(sentinelKey);
+    await saveDraft("wizard:stale-forged-sentinel", { photo: fileRefPointer(sentinelKey) });
+    await backdate("wizard:stale-forged-sentinel", 31);
 
     await dispatchCleanup();
 
-    await waitFor(async () => {
-      expect(await draftExists("wizard:stale-forged")).toBe(false);
+    await waitFor(() => {
+      expect(providerA.keys()).not.toContain(sentinelKey);
     });
+    expect(await draftExists("wizard:stale-forged")).toBe(false);
     expect(providerA.keys()).toContain(forgedKey);
   });
 
@@ -304,18 +325,28 @@ describe("form-draft cleanup job — FileRef release (#1915)", () => {
     await seedFileRef(key);
     // The photo was uploaded when the domain entity was originally created —
     // long before this editing session's draft. backdate() (below) also
-    // ages the draft row to 31 days, so the file must be aged further still
+    // ages the draft row to 40 days, so the file must be aged further still
     // to model "predates the draft" rather than "same moment".
     await backdateFileRef(key, 60);
 
     await saveDraft("wizard:stale-with-prefilled-photo", { photo: fileRefPointer(key) });
-    await backdate("wizard:stale-with-prefilled-photo", 31);
+    await backdate("wizard:stale-with-prefilled-photo", 40);
+
+    // Release sentinel — see the forged-draft-value test above for why a
+    // plain draftExists wait can't prove this row's release was actually
+    // (correctly) skipped, only that it hasn't been attempted yet.
+    const sentinelKey = "tenant-a/vehicle/prefilled-sentinel.jpg";
+    await providerA.write(sentinelKey, new Uint8Array([7]), "image/jpeg");
+    await seedFileRef(sentinelKey);
+    await saveDraft("wizard:stale-with-prefilled-sentinel", { photo: fileRefPointer(sentinelKey) });
+    await backdate("wizard:stale-with-prefilled-sentinel", 31);
 
     await dispatchCleanup();
 
-    await waitFor(async () => {
-      expect(await draftExists("wizard:stale-with-prefilled-photo")).toBe(false);
+    await waitFor(() => {
+      expect(providerA.keys()).not.toContain(sentinelKey);
     });
+    expect(await draftExists("wizard:stale-with-prefilled-photo")).toBe(false);
     // The live domain entity this draft was editing still references `key`.
     expect(providerA.keys()).toContain(key);
   });
@@ -336,9 +367,9 @@ describe("form-draft cleanup job — FileRef release (#1915)", () => {
 
     await dispatchCleanup();
 
-    await waitFor(async () => {
-      expect(await draftExists("wizard:new:create-mode-stale")).toBe(false);
+    await waitFor(() => {
+      expect(providerA.keys()).not.toContain(key);
     });
-    expect(providerA.keys()).not.toContain(key);
+    expect(await draftExists("wizard:new:create-mode-stale")).toBe(false);
   });
 });