@cosmicdrift/kumiko-bundled-features 0.225.0 → 0.227.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.225.0",
+  "version": "0.227.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -130,12 +130,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.225.0",
-    "@cosmicdrift/kumiko-framework": "0.225.0",
-    "@cosmicdrift/kumiko-headless": "0.225.0",
-    "@cosmicdrift/kumiko-renderer": "0.225.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.225.0",
-    "@cosmicdrift/kumiko-types": "0.225.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.227.0",
+    "@cosmicdrift/kumiko-framework": "0.227.0",
+    "@cosmicdrift/kumiko-headless": "0.227.0",
+    "@cosmicdrift/kumiko-renderer": "0.227.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.227.0",
+    "@cosmicdrift/kumiko-types": "0.227.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -164,7 +164,7 @@
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
     "@types/qrcode": "^1.5.5",
-    "@cosmicdrift/kumiko-locale-de": "0.225.0",
-    "@cosmicdrift/kumiko-locale-es": "0.225.0"
+    "@cosmicdrift/kumiko-locale-de": "0.227.0",
+    "@cosmicdrift/kumiko-locale-es": "0.227.0"
   }
 }

package/src/auth-email-password/__tests__/seed-admin-guarded.integration.test.ts

@@ -0,0 +1,183 @@
+// offlot#114 — DB integration for seedAdminGuarded, the boot-seed variant
+// of seedAdmin that survives a blind-index miss on an otherwise-existing
+// account. Runs against a KMS + blind-index setup, which is the only
+// configuration where the bug reproduces: `email` holds per-row ciphertext,
+// so seedAdmin's idempotency check can only match through the deterministic
+// `email_bidx` companion column.
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  configureBlindIndexKey,
+  configurePiiSubjectKms,
+  InMemoryKmsAdapter,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable, eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import {
+  resetBlindIndexKeyForTests,
+  resetPiiSubjectKmsForTests,
+} from "@cosmicdrift/kumiko-framework/testing";
+import { createConfigFeature } from "../../config/feature";
+import { createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+import { createTenantFeature } from "../../tenant/feature";
+import { tenantMembershipsTable } from "../../tenant/membership-table";
+import { tenantEntity, tenantTable } from "../../tenant/schema/tenant";
+import { createUserFeature } from "../../user/feature";
+import { userEntity, userTable } from "../../user/schema/user";
+import { seedUser } from "../../user/seeding";
+import { seedAdmin, seedAdminGuarded } from "../seeding";
+
+const BLIND_INDEX_KEY_B64 = Buffer.alloc(32, 14).toString("base64");
+const TENANT_114: TenantId = "00000000-0000-4000-8000-0000000001d4" as TenantId;
+const SYSADMIN_EMAIL = "sysadmin@offlot.app";
+
+const seedOptions = {
+  email: SYSADMIN_EMAIL,
+  password: "sysadmin-pw-114",
+  displayName: "Sysadmin",
+  globalRoles: ["SystemAdmin"],
+  memberships: [
+    { tenantId: TENANT_114, tenantKey: "demo-114", tenantName: "Demo 114", roles: ["TenantAdmin"] },
+  ],
+} as const;
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  const resolver = createConfigResolver();
+  stack = await setupTestStack({
+    features: [createConfigFeature(), createUserFeature(), createTenantFeature()],
+    extraContext: { configResolver: resolver },
+  });
+  await unsafeCreateEntityTable(stack.db, tenantEntity);
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafePushTables(stack.db, { configValuesTable, tenantMembershipsTable });
+  await createEventsTable(stack.db);
+}, 60_000);
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantTable.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${userTable.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${eventsTable.tableName}"`);
+  configurePiiSubjectKms(new InMemoryKmsAdapter());
+  configureBlindIndexKey(BLIND_INDEX_KEY_B64);
+});
+
+afterEach(() => {
+  resetPiiSubjectKmsForTests();
+  resetBlindIndexKeyForTests();
+});
+
+async function userIds(): Promise<readonly string[]> {
+  const rows = await selectMany<{ id: string }>(stack.db, userTable);
+  return rows.map((r) => r.id);
+}
+
+async function membershipUserIds(): Promise<readonly string[]> {
+  const rows = await selectMany<{ userId: string }>(stack.db, tenantMembershipsTable);
+  return rows.map((r) => r.userId);
+}
+
+/** Reproduces the offlot#112 row shape in prod: the email column keeps its
+ *  ciphertext, but the blind index is blank — as it is for rows written
+ *  before KUMIKO_BLIND_INDEX_KEY existed, or after a subject-key erase. */
+async function blankBlindIndex(): Promise<void> {
+  await asRawClient(stack.db).unsafe(`UPDATE "${userTable.tableName}" SET email_bidx = NULL`);
+}
+
+describe("seedAdminGuarded (offlot#114)", () => {
+  test("re-seeding twice on an empty DB stays idempotent", async () => {
+    const first = await seedAdminGuarded(stack.db, seedOptions);
+    const second = await seedAdminGuarded(stack.db, seedOptions);
+
+    expect(second.id).toBe(first.id);
+    expect(await userIds()).toEqual([first.id]);
+    expect(await membershipUserIds()).toEqual([first.id]);
+  });
+
+  test("a blank blind index no longer produces a second account", async () => {
+    const first = await seedAdminGuarded(stack.db, seedOptions);
+    await blankBlindIndex();
+
+    const second = await seedAdminGuarded(stack.db, seedOptions);
+
+    expect(second.id).toBe(first.id);
+    expect(await userIds()).toEqual([first.id]);
+    // Membership is reconciled onto the existing account, not a new identity.
+    expect(await membershipUserIds()).toEqual([first.id]);
+  });
+
+  test("unguarded seedAdmin still duplicates on a blank blind index — the gap seedAdminGuarded covers", async () => {
+    // Pins the framework behaviour the guard compensates for: seedUser's
+    // existence check is bidx-only, and neither unique index on the user
+    // table can catch this (the plaintext unique index sits on randomized
+    // ciphertext, the bidx unique index is partial WHERE email_bidx IS NOT
+    // NULL). If this ever fails, seedAdmin's idempotency check changed and
+    // this guard can be revisited.
+    const first = await seedAdmin(stack.db, seedOptions);
+    await blankBlindIndex();
+
+    const second = await seedAdmin(stack.db, seedOptions);
+
+    expect(second.id).not.toBe(first.id);
+    expect(await userIds()).toHaveLength(2);
+  });
+
+  test("pre-existing duplicates are reused, never extended", async () => {
+    // Build the exact prod state: two ciphertext rows for one email, the
+    // older one with a blank blind index.
+    const canonical = await seedAdmin(stack.db, seedOptions);
+    await blankBlindIndex();
+    const duplicate = await seedAdmin(stack.db, seedOptions);
+    expect(await userIds()).toHaveLength(2);
+
+    // Guards against a false pass: the canonical pick must be driven by
+    // insertedAt ordering, not a coincidental id sort — assert the rows
+    // actually carry distinct, comparable Temporal.Instant timestamps.
+    const rows = await selectMany<{ id: string; insertedAt: { epochNanoseconds: bigint } }>(
+      stack.db,
+      userTable,
+    );
+    const canonicalRow = rows.find((r) => r.id === canonical.id);
+    const duplicateRow = rows.find((r) => r.id === duplicate.id);
+    expect(typeof canonicalRow?.insertedAt.epochNanoseconds).toBe("bigint");
+    expect(typeof duplicateRow?.insertedAt.epochNanoseconds).toBe("bigint");
+    expect(
+      canonicalRow!.insertedAt.epochNanoseconds < duplicateRow!.insertedAt.epochNanoseconds,
+    ).toBe(true);
+
+    const seeded = await seedAdminGuarded(stack.db, seedOptions);
+
+    // Oldest row wins.
+    expect(seeded.id).toBe(canonical.id);
+    expect(seeded.id).not.toBe(duplicate.id);
+    // No third row: the guard refuses to add to a broken state.
+    expect(await userIds()).toHaveLength(2);
+  });
+
+  test("unrelated single-row accounts are untouched", async () => {
+    const unrelated = await seedUser(stack.db, {
+      email: "dealer@offlot.app",
+      displayName: "Dealer",
+    });
+    const admin = await seedAdminGuarded(stack.db, seedOptions);
+    await blankBlindIndex();
+    await seedAdminGuarded(stack.db, seedOptions);
+
+    expect(await userIds()).toHaveLength(2);
+    expect((await userIds()).slice().sort()).toEqual([unrelated.id, admin.id].sort());
+  });
+});

package/src/auth-email-password/seeding.ts

@@ -12,7 +12,12 @@
 // Damit Sample-Server und Tests keine drei sub-paths zusammensammeln
 // müssen.
 
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  configuredPiiSubjectKms,
+  decryptPiiFieldValues,
+  type LocalKeyKmsAdapter,
+} from "@cosmicdrift/kumiko-framework/crypto";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { ConflictError } from "@cosmicdrift/kumiko-framework/errors";
@@ -21,7 +26,7 @@ import { hashPassword } from "../shared";
 // kumiko-lint-ignore cross-feature-import auth-tests need user+tenant seed-helpers
 import { type SeedTenantHooks, seedTenant, seedTenantMembership } from "../tenant/seeding";
 // kumiko-lint-ignore cross-feature-import signup create-only guard reads the user projection by email
-import { userTable } from "../user/schema/user";
+import { USER_STATUS, userTable } from "../user/schema/user";
 // kumiko-lint-ignore cross-feature-import auth-tests need user+tenant seed-helpers
 import { seedUser } from "../user/seeding";
 
@@ -235,3 +240,108 @@ export async function seedAdmin(
 
   return { id: userId };
 }
+
+// offlot#114 — seedAdmin's idempotency check is a plain fetchOne(email),
+// which the query layer rewrites into `(email = $plaintext OR
+// email_bidx = $hmac)` once a blind-index key is configured. Under KMS
+// encryption `email` holds per-row ciphertext, so only the bidx arm can
+// ever match — and it misses whenever a row's `email_bidx` is NULL (written
+// before the key existed, or after a subject-key erase) or was computed
+// with a since-rotated key. seedAdmin then inserts a second row for an
+// email that already has an account; neither the plaintext unique index
+// (sits on randomized ciphertext) nor the partial bidx unique index (WHERE
+// email_bidx IS NOT NULL, so a NULL row never collides) catches it.
+//
+// seedAdminGuarded is a separate, additive boot-seed guard — NOT a change
+// to seedUser/seedAdmin/provisionSignupAccount, which also run on every
+// real self-signup request and can't afford a decrypt-scan fallback there.
+// Use this only where seedAdmin already runs (dev-boot / sample-server /
+// bootstrap scripts), never as a login or signup hot path.
+
+type ActiveUserRow = {
+  readonly id: string;
+  readonly email: string;
+  readonly insertedAt: { readonly epochNanoseconds: bigint };
+};
+
+function compareInsertedAt(a: ActiveUserRow["insertedAt"], b: ActiveUserRow["insertedAt"]): number {
+  if (a.epochNanoseconds < b.epochNanoseconds) return -1;
+  if (a.epochNanoseconds > b.epochNanoseconds) return 1;
+  return 0;
+}
+
+/** Oldest row wins, tie-broken by id — the same rule a manual duplicate
+ *  cleanup would apply, so this guard and any later cleanup never disagree
+ *  on which row is the survivor. */
+function pickCanonicalUserId(rows: readonly ActiveUserRow[]): string {
+  const sorted = [...rows].sort((a, b) => {
+    const byTime = compareInsertedAt(a.insertedAt, b.insertedAt);
+    return byTime !== 0 ? byTime : a.id.localeCompare(b.id);
+  });
+  const first = sorted[0];
+  if (first === undefined) throw new Error("pickCanonicalUserId: empty group");
+  return first.id;
+}
+
+async function findExistingUserIdForEmail(
+  db: DbConnection,
+  kms: LocalKeyKmsAdapter,
+  email: string,
+): Promise<string | undefined> {
+  // ponytail: decrypts every active user row to compare emails. Fine at
+  // boot-seed scale (tens of accounts, once per boot); if the user table
+  // grows past a few thousand rows, narrow this to rows whose email_bidx is
+  // NULL or doesn't match the expected HMAC — only those need decrypting.
+  const rows = await selectMany<ActiveUserRow>(db, userTable, {
+    isDeleted: false,
+    status: { ne: USER_STATUS.Deleted },
+  });
+  const matches: ActiveUserRow[] = [];
+  for (const row of rows) {
+    // Compared byte-exact, deliberately not case-folded: email_bidx is an
+    // HMAC over the raw value and login matches case-sensitively, so a case
+    // variant is a different account to every other code path.
+    const decrypted = await decryptPiiFieldValues({ email: row.email }, ["email"], kms, {
+      requestId: "seed-admin-guarded",
+    });
+    if (decrypted["email"] === email) matches.push(row);
+  }
+  return matches.length === 0 ? undefined : pickCanonicalUserId(matches);
+}
+
+/**
+ * Boot-seed variant of seedAdmin that survives a blind-index miss on an
+ * otherwise-existing account (see the module comment above). Not for the
+ * self-signup hot path — seedAdmin/seedUser stay the unguarded entry point
+ * there.
+ *
+ * No cheap `fetchOne` fast path here on purpose: a hit there only proves
+ * SOME row matches (plaintext or bidx), never that it's the canonical one —
+ * a stale row's bidx can go NULL while a later duplicate's stays valid, so
+ * fetchOne keeps finding the duplicate forever and the seed never converges
+ * on the oldest row. The only cheap short-circuit that stays correct is
+ * skipping the scan entirely when no KMS is configured at all (plaintext
+ * DBs have no bidx ambiguity to guard against in the first place).
+ */
+export async function seedAdminGuarded(
+  db: DbConnection,
+  options: SeedAdminOptions,
+): Promise<{ id: string }> {
+  const kms = configuredPiiSubjectKms();
+  if (kms === undefined) return seedAdmin(db, options);
+
+  const existingId = await findExistingUserIdForEmail(db, kms, options.email);
+  if (existingId === undefined) return seedAdmin(db, options);
+
+  const by = options.by ?? TestUsers.systemAdmin;
+  for (const m of options.memberships) {
+    await seedTenant(db, { id: m.tenantId, key: m.tenantKey, name: m.tenantName, by });
+    await seedTenantMembership(db, {
+      userId: existingId,
+      tenantId: m.tenantId,
+      roles: m.roles,
+      by,
+    });
+  }
+  return { id: existingId };
+}

package/src/cap-overview/__tests__/cap-overview-security.integration.test.ts

@@ -42,6 +42,15 @@ const testCap: CapSpec = {
   usage: async (_db, tenantId) => USAGE_BY_TENANT[tenantId] ?? 0,
 };
 
+// Never wired up for any tenant — proves the "not measured" state renders
+// as null, not 0, all the way through the real query handler.
+const unmeasuredCap: CapSpec = {
+  id: "unmeasured",
+  label: "test.cap.unmeasured",
+  limit: () => 10,
+  usage: async () => null,
+};
+
 let stack: TestStack;
 let db: DbConnection;
 
@@ -54,7 +63,7 @@ beforeAll(async () => {
       createTenantLifecycleFeature(),
       billingFoundationFeature,
       tierEngineFeature,
-      createCapOverviewFeature({ caps: [testCap] }),
+      createCapOverviewFeature({ caps: [testCap, unmeasuredCap] }),
     ],
   });
   db = stack.db;
@@ -111,24 +120,25 @@ describe("cap-overview tenant isolation", () => {
 
   test("TenantAdmin(A) without override sees exactly A's own numbers, not a sum", async () => {
     const tenantAdminA = createTestUser({ id: 90014, tenantId: TENANT_A, roles: ["TenantAdmin"] });
-    const result = await stack.http.queryOk<{ rows: readonly { used: number }[] }>(
-      CapOverviewQueries.capsUsage,
-      {},
-      tenantAdminA,
-    );
-    expect(result.rows).toHaveLength(1);
-    expect(result.rows[0]?.used).toBe(USAGE_BY_TENANT[TENANT_A]);
+    const result = await stack.http.queryOk<{
+      rows: readonly { id: string; used: number | null; percent: number | null }[];
+    }>(CapOverviewQueries.capsUsage, {}, tenantAdminA);
+    expect(result.rows).toHaveLength(2);
+    const widgetsRow = result.rows.find((row) => row.id === testCap.id);
+    expect(widgetsRow?.used).toBe(USAGE_BY_TENANT[TENANT_A]);
+
+    const unmeasuredRow = result.rows.find((row) => row.id === unmeasuredCap.id);
+    expect(unmeasuredRow?.used).toBeNull();
+    expect(unmeasuredRow?.percent).toBeNull();
   });
 
   test("SystemAdmin can read tenant B's usage via override", async () => {
     const sysAdmin = createTestUser({ id: 90015, tenantId: TENANT_A, roles: ["SystemAdmin"] });
-    const result = await stack.http.queryOk<{ rows: readonly { used: number }[] }>(
-      CapOverviewQueries.capsUsage,
-      { tenantId: TENANT_B },
-      sysAdmin,
-    );
-    expect(result.rows).toHaveLength(1);
-    expect(result.rows[0]?.used).toBe(USAGE_BY_TENANT[TENANT_B]);
+    const result = await stack.http.queryOk<{
+      rows: readonly { id: string; used: number | null }[];
+    }>(CapOverviewQueries.capsUsage, { tenantId: TENANT_B }, sysAdmin);
+    const widgetsRow = result.rows.find((row) => row.id === testCap.id);
+    expect(widgetsRow?.used).toBe(USAGE_BY_TENANT[TENANT_B]);
   });
 
   test("SystemAdmin sees both tenants on the list, each with its own numbers", async () => {

package/src/cap-overview/handlers/caps-usage.query.ts

@@ -65,6 +65,19 @@ export function createCapsUsageQuery(caps: readonly CapSpec[]): QueryHandlerDefi
         caps.map(async (cap) => {
           const used = await cap.usage(db, targetTenantId);
           const limit = cap.limit(tier);
+          if (used === null) {
+            return {
+              id: cap.id,
+              label: cap.label,
+              used: null,
+              limit,
+              fraction: 0,
+              tone: "default" as const,
+              percent: null,
+              ...(cap.icon !== undefined && { icon: cap.icon }),
+              ...(cap.accentColor !== undefined && { accentColor: cap.accentColor }),
+            };
+          }
           const fraction = computeFraction(used, limit);
           return {
             id: cap.id,

package/src/cap-overview/handlers/tenant-caps-list.query.ts

@@ -182,12 +182,12 @@ export function createTenantCapsListQuery(caps: readonly CapSpec[], listCaps: re
       // N+1 avoidance: usage is computed only for this page's tenant ids,
       // never for the full tenant set.
       const pageTenantIds = page.map((row) => row.tenantId);
-      const usageByCap = new Map<string, Map<string, number>>();
+      const usageByCap = new Map<string, Map<string, number | null>>();
       for (const cap of listedCaps) {
         if (cap.usageBatch) {
           usageByCap.set(cap.id, await cap.usageBatch(db, pageTenantIds));
         } else {
-          const perTenant = new Map<string, number>();
+          const perTenant = new Map<string, number | null>();
           for (const tenantId of pageTenantIds) {
             perTenant.set(tenantId, await cap.usage(db, tenantId));
           }
@@ -198,9 +198,15 @@ export function createTenantCapsListQuery(caps: readonly CapSpec[], listCaps: re
       const rows: TenantCapsListRow[] = page.map((row) => {
         const capFields: Record<string, CapUsage> = {};
         for (const cap of listedCaps) {
-          const used = usageByCap.get(cap.id)?.get(row.tenantId) ?? 0;
+          // A tenant absent from the map still means 0 (existing behavior);
+          // only an explicit `null` value means "not measured".
+          const rawUsed = usageByCap.get(cap.id)?.get(row.tenantId);
+          const used = rawUsed === undefined ? 0 : rawUsed;
           const limit = cap.limit(row.tier);
-          capFields[capFieldName(cap.id)] = { used, limit, fraction: computeFraction(used, limit) };
+          capFields[capFieldName(cap.id)] =
+            used === null
+              ? { used: null, limit, fraction: 0 }
+              : { used, limit, fraction: computeFraction(used, limit) };
         }
         return {
           tenantId: row.tenantId,

package/src/cap-overview/i18n.ts

@@ -12,6 +12,7 @@ export const CAP_OVERVIEW_I18N: Readonly<Record<string, LocalizedString>> = {
   "cap-overview.platform.filter.tenant": { en: "Tenant" },
   "cap-overview.cards.empty": { en: "No caps configured for this tenant." },
   "cap-overview.cards.loading": { en: "Loading usage…" },
+  "cap-overview.notMeasured": { en: "Not measured yet" },
   "cap-overview.errors.progressPrimitiveMissing": {
     en: "Usage bar unavailable — Progress primitive is not registered.",
   },

package/src/cap-overview/types.ts

@@ -15,14 +15,19 @@ export type CapSpec = {
   readonly id: string;
   readonly label: string;
   readonly limit: (tier: string) => number;
-  readonly usage: (db: TenantDb, tenantId: TenantId) => Promise<number>;
+  // `null` means "no measurement exists yet for this cap" (not "0 used") —
+  // callers that haven't wired up instrumentation return null instead of a
+  // number they don't actually have.
+  readonly usage: (db: TenantDb, tenantId: TenantId) => Promise<number | null>;
   // Batched usage lookup for the tenant-caps:list screen — called once per
   // cap with the current page's tenant ids instead of once per (cap, row).
-  // Optional: falls back to per-row `usage()` when absent.
+  // Optional: falls back to per-row `usage()` when absent. A tenant absent
+  // from the returned map still means 0 (unchanged) — only an explicit
+  // `null` value means "not measured".
   readonly usageBatch?: (
     db: TenantDb,
     tenantIds: readonly TenantId[],
-  ) => Promise<Map<TenantId, number>>;
+  ) => Promise<Map<TenantId, number | null>>;
   readonly unit?: "count" | "mb" | "tokens";
   /** Icon chip on the dashboard cards. Optional — omitted renders the card
    *  without an icon, same as before this field existed. */
@@ -36,7 +41,9 @@ export type CapSpec = {
 export type CapUsageTone = "default" | "warn" | "danger";
 
 export type CapUsage = {
-  readonly used: number;
+  // `null` means not measured yet — `fraction`/`tone` stay non-nullable
+  // (0 / "default") so no consumer needs null-arithmetic to render.
+  readonly used: number | null;
   readonly limit: number;
   readonly fraction: number;
 };
@@ -45,7 +52,7 @@ export type CapUsageWithMeta = CapUsage & {
   readonly id: string;
   readonly label: string;
   readonly tone: CapUsageTone;
-  readonly percent: number;
+  readonly percent: number | null;
   readonly icon?: CapIconKey;
   readonly accentColor?: string;
 };

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

@@ -83,6 +83,19 @@ function capRow(overrides: Partial<CapUsageWithMeta> = {}): CapUsageWithMeta {
   };
 }
 
+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();
@@ -187,6 +200,39 @@ describe("CapCardsPanel", () => {
     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 };
 

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

@@ -23,6 +23,20 @@ function fillClass(): string | undefined {
 }
 
 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(

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

@@ -35,6 +35,14 @@ const CAP_ICONS: Record<CapIconKey, ComponentType<{ className?: string }>> = {
   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();
@@ -81,14 +89,16 @@ export function CapCardsPanel({ filterParams }: ExtensionSectionProps): ReactNod
             key={cap.id}
             icon={Icon !== undefined ? <Icon className="size-4" /> : undefined}
             label={t(cap.label)}
-            value={`${cap.used} / ${cap.limit}`}
+            value={isMeasured(cap) ? `${cap.used} / ${cap.limit}` : "—"}
             {...(cap.accentColor !== undefined && { accentColor: cap.accentColor })}
             testId="cap-card"
           >
             <div className="flex flex-col gap-2">
-              <div className="flex items-center justify-between gap-2">
-                <StatusBadge tone={TONE_TO_STATUS[cap.tone]}>{`${cap.percent}%`}</StatusBadge>
-              </div>
+              {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>

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

@@ -15,6 +15,15 @@ export function CapUsageBar({
 }): 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 ? (

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

@@ -5,10 +5,10 @@ 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 value === "object" &&
-    value !== null &&
-    typeof (value as { used?: unknown }).used === "number" &&
+    (typeof used === "number" || used === null) &&
     typeof (value as { limit?: unknown }).limit === "number" &&
     typeof (value as { fraction?: unknown }).fraction === "number"
   );

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);
   });
 });

package/src/notes-history/__tests__/notes-section.test.tsx

@@ -131,12 +131,12 @@ describe("NotesSection — entry display", () => {
   test("note body and meta line render as two distinct nodes, not one run-on line", async () => {
     const view = renderSection();
     await waitFor(() => {
-      if (view.queryByTestId("notes-section-row-note-1-body") === null) {
+      if (view.queryByTestId("notes-section-body-note-1") === null) {
         throw new Error("row not rendered yet");
       }
     });
-    const bodyEl = view.getByTestId("notes-section-row-note-1-body");
-    const metaEl = view.getByTestId("notes-section-row-note-1-meta");
+    const bodyEl = view.getByTestId("notes-section-body-note-1");
+    const metaEl = view.getByTestId("notes-section-meta-note-1");
     expect(bodyEl).not.toBe(metaEl);
     expect(bodyEl.textContent).toBe(NOTE_BODY);
     expect(metaEl.textContent).not.toContain(NOTE_BODY);
@@ -145,14 +145,25 @@ describe("NotesSection — entry display", () => {
     expect(row.className).toContain("flex-col");
   });
 
+  test("the row testid prefix matches exactly one node per note, not three", async () => {
+    const view = renderSection();
+    await waitFor(() => {
+      if (view.queryByTestId("notes-section-row-note-1") === null) {
+        throw new Error("rows not rendered yet");
+      }
+    });
+    const matches = view.container.querySelectorAll('[data-testid^="notes-section-row-"]');
+    expect(matches.length).toBe(NOTE_ROWS.length);
+  });
+
   test("a stamped authorName renders as the author, never the raw authorId", async () => {
     const view = renderSection();
     await waitFor(() => {
-      if (view.queryByTestId("notes-section-row-note-1-meta") === null) {
+      if (view.queryByTestId("notes-section-meta-note-1") === null) {
         throw new Error("row not rendered yet");
       }
     });
-    const metaEl = view.getByTestId("notes-section-row-note-1-meta");
+    const metaEl = view.getByTestId("notes-section-meta-note-1");
     expect(metaEl.textContent).not.toContain(AUTHOR_ID);
     expect(metaEl.textContent).toContain(AUTHOR_NAME);
   });
@@ -160,22 +171,22 @@ describe("NotesSection — entry display", () => {
   test("a null authorName (legacy row) renders the placeholder", async () => {
     const view = renderSection();
     await waitFor(() => {
-      if (view.queryByTestId("notes-section-row-note-2-meta") === null) {
+      if (view.queryByTestId("notes-section-meta-note-2") === null) {
         throw new Error("row not rendered yet");
       }
     });
-    const metaEl = view.getByTestId("notes-section-row-note-2-meta");
+    const metaEl = view.getByTestId("notes-section-meta-note-2");
     expect(metaEl.textContent).toContain("Unknown author");
   });
 
   test("a shredded authorName sentinel renders the placeholder, never [[erased]]", async () => {
     const view = renderSection();
     await waitFor(() => {
-      if (view.queryByTestId("notes-section-row-note-3-meta") === null) {
+      if (view.queryByTestId("notes-section-meta-note-3") === null) {
         throw new Error("row not rendered yet");
       }
     });
-    const metaEl = view.getByTestId("notes-section-row-note-3-meta");
+    const metaEl = view.getByTestId("notes-section-meta-note-3");
     expect(metaEl.textContent).toContain("Unknown author");
     expect(metaEl.textContent).not.toContain(PII_ERASED_SENTINEL);
   });
@@ -183,11 +194,11 @@ describe("NotesSection — entry display", () => {
   test("date renders formatted, never the raw ISO timestamp", async () => {
     const view = renderSection();
     await waitFor(() => {
-      if (view.queryByTestId("notes-section-row-note-1-meta") === null) {
+      if (view.queryByTestId("notes-section-meta-note-1") === null) {
         throw new Error("row not rendered yet");
       }
     });
-    const metaEl = view.getByTestId("notes-section-row-note-1-meta");
+    const metaEl = view.getByTestId("notes-section-meta-note-1");
     expect(metaEl.textContent).not.toContain(INSERTED_AT);
     expect(metaEl.textContent).toContain(formatWhen(INSERTED_AT));
   });

package/src/notes-history/web/notes-section.tsx

@@ -149,8 +149,8 @@ export function NotesSection({
               data-testid={`notes-section-row-${n.id}`}
               className="flex flex-col gap-1 rounded-md border p-2"
             >
-              <Text testId={`notes-section-row-${n.id}-body`}>{n.body}</Text>
-              <Text variant="small" testId={`notes-section-row-${n.id}-meta`}>
+              <Text testId={`notes-section-body-${n.id}`}>{n.body}</Text>
+              <Text variant="small" testId={`notes-section-meta-${n.id}`}>
                 {t("notesHistory.section.meta", {
                   author: displayAuthorName(n.authorName, t("notesHistory.section.authorUnknown")),
                   date: formatWhen(n.insertedAt),

package/src/sessions/handlers/detail.query.ts

@@ -6,10 +6,21 @@ import { userSessionTable } from "../schema/user-session";
 
 // Admin single-session inspector — mirrors list.query's decrypt handling for
 // the one-row case. ctx.db (TenantDb) applies tenant-scoping automatically.
+const sessionRowSchema = z.object({
+  id: z.string(),
+  userId: z.string(),
+  createdAt: z.unknown(),
+  expiresAt: z.unknown(),
+  revokedAt: z.unknown(),
+  ip: z.string().nullable(),
+  userAgent: z.string().nullable(),
+});
+
 export const detailQuery = defineQueryHandler({
   name: "user-session:detail",
   schema: z.object({ id: z.uuid() }),
   access: { roles: access.admin },
+  outputSchema: sessionRowSchema.nullable(),
   handler: async (query, ctx) => {
     const row = await fetchOne<{
       id: string;

package/src/sessions/handlers/list.query.ts

@@ -33,6 +33,20 @@ export const listQuery = definePagedQueryHandler({
     sortDirection: z.enum(["asc", "desc"]).optional(),
   }),
   access: { roles: access.admin },
+  outputSchema: z.object({
+    rows: z.array(
+      z.object({
+        id: z.string(),
+        userId: z.string(),
+        createdAt: z.unknown(),
+        expiresAt: z.unknown(),
+        revokedAt: z.unknown(),
+        ip: z.string().nullable(),
+        userAgent: z.string().nullable(),
+      }),
+    ),
+    nextCursor: z.string().nullable(),
+  }),
   handler: async (query, ctx) => {
     const requestedSort = query.payload.sort;
     const sortColumn: SortableColumn =