@tokenoftrust/storefront-runner 4.10.1 → 4.11.1

package/apps/storefront/src/lib/orders/vault/orderContactVault.ts

@@ -1,70 +1,139 @@
 /**
- * The order contact vault: one sealed contact per order, in `order_contact_vault`
- * (migrations-apps/0021). Every effect is one statement or one D1 batch, so a check and its write
- * can never be split by a concurrent intake, erase or purge:
+ * The order contact vault (migrations-apps/0022): every personal field of an order's contact is its
+ * own AES-256-GCM ciphertext under the tenant's KMS-wrapped order-contact data key, held per field
+ * group (identity, email, phone, ship, bill) by the declared retention rules. The row keyed by a
+ * random fact_id is also the long-lived facts row: once its last group is cleared it is detached
+ * from the order and keeps only month, zip3, region, country and totals.
  *
- *  - seal: a conditional vault insert plus a replay row recorded only when THIS command sealed;
- *    every refused outcome writes nothing.
- *  - read: the audit row commits (with the staff quota in the same statement) before any decrypt.
- *  - erase: audit, tombstone and delete commit together.
- *  - purge: tombstone and delete expired rows together, so a purged contact cannot be resealed.
+ * Every effect is one statement or one D1 batch, so a check and its write can never be split:
+ *  - seal: [new data-key rows] + conditional vault insert + marker + replay (both conditioned on the
+ *    vault row this command sealed) + key cleanup. Every refused or racing outcome commits nothing.
+ *  - read / list: the audit row commits (staff quota in the same statement) before any decrypt.
+ *  - erase: audit, group clearing and detach commit together.
+ *  - purge: one clock reading; each page is one batch.
  *
- * Nothing here logs. Errors and outcomes carry fixed codes only.
+ *  - rotation: retire and replace due keys, recompute blind indexes under a retired kid (one
+ *    conditioned update per row), then delete unreferenced retired keys.
+ *
+ * Nothing here logs. Errors and outcomes carry fixed codes only; fact_id never leaves this module.
  */
 import type { Queryable, QueryStatement } from "../../catalog/d1/catalog.js";
+import { VaultKeyUnavailableError, type DataKeyPurpose, type EncryptionContext, type KmsClient } from "@/lib/customers/contactVault/kms.js";
+import {
+  activeKey,
+  cleanupStatement,
+  deleteUnreferencedRetiredKeys,
+  keyForKid,
+  rotateDueKeys,
+} from "@/lib/customers/contactVault/dataKeys.js";
+import { openField, sealField, type FieldBinding } from "@/lib/customers/contactVault/fieldEnvelope.js";
+import { blindIndex, normalizeEmail, normalizePhone } from "@/lib/customers/contactVault/blindIndex.js";
 import {
-  openVaultRecord,
-  sealVaultRecord,
-  VaultKeyUnavailableError,
-  type VaultBinding,
-  type VaultKeyring,
-} from "@/lib/customers/contactVault/envelope.js";
-import { expiresAtFor, isReadable, notAfterFrom, readInstant, terminalExpiryFrom } from "@/lib/customers/contactVault/retention.js";
-import { orderContactPlaintext, sameOrderContact, type OrderContact, type OrderContactCommand } from "./orderContact.js";
+  TERMINAL_AT_SQL,
+  isGroupReadable,
+  previewDeleteAt,
+  readInstant,
+  readStampInstant,
+  rederiveGroup,
+  sealRetention,
+} from "@/lib/customers/contactVault/retention.js";
+import { GROUPS, RETENTION_POLICY, applicableRules, rulesForTenant, type Group, type RetentionPolicy } from "@/lib/customers/contactVault/retentionPolicy.js";
+import { zip3 } from "@/lib/customers/contactVault/zip3.js";
 import {
+  AUDIT_RECORD_IDS_MAX,
   admitAudit,
+  auditRecordIds,
   auditStatement,
   batchAuditStatement,
   type ContactActor,
   type VaultStage,
 } from "@/lib/customers/contactVault/contactAudit.js";
+import { orderContactPlaintext, sameOrderContact, type ContactAddress, type OrderContactCommand } from "./orderContact.js";
 
-export type SealOutcome =
-  | { ok: true; status: 200; duplicate: boolean }
-  | {
-      ok: false;
-      status: 401 | 409 | 410 | 503;
-      reason: "replay" | "order-unknown" | "order-time-unreadable" | "contact-conflict" | "contact-expired" | "contact-erased" | "vault-key-unavailable";
-    };
+export type { Group } from "@/lib/customers/contactVault/retentionPolicy.js";
 
-export type ReadOutcome =
-  | { ok: true; contact: OrderContact; expiresAt: string }
-  | { ok: false; status: 404 | 429 | 503; reason: "not-found" | "quota" | "audit-unavailable" | "vault-key-unavailable" };
+// ---------------------------------------------------------------------------------------------
+// Layout
+// ---------------------------------------------------------------------------------------------
 
-export type EraseOutcome =
-  | { ok: true }
-  | { ok: false; status: 404 | 429 | 503; reason: "not-found" | "quota" | "audit-unavailable" };
+interface GroupLayout {
+  sealed: readonly string[];
+  bidx: string | null;
+  plain: readonly string[];
+}
 
-interface OrderRow {
-  placed_at: unknown;
-  fulfillment_state: unknown;
+const LAYOUT: Readonly<Record<Group, GroupLayout>> = {
+  identity: { sealed: ["name_ct", "company_ct"], bidx: null, plain: [] },
+  email: { sealed: ["email_ct"], bidx: "email_bidx", plain: [] },
+  phone: { sealed: ["phone_ct"], bidx: "phone_bidx", plain: [] },
+  ship: { sealed: ["ship_name_ct", "ship_company_ct", "ship_line1_ct", "ship_line2_ct"], bidx: null, plain: ["ship_city", "ship_postal_code"] },
+  bill: { sealed: ["bill_name_ct", "bill_company_ct", "bill_line1_ct", "bill_line2_ct"], bidx: null, plain: ["bill_city", "bill_postal_code"] },
+};
+
+function groupColumns(group: Group): string[] {
+  const layout = LAYOUT[group];
+  return [...layout.sealed, ...(layout.bidx ? [layout.bidx] : []), ...layout.plain];
+}
+
+/** SQL: the group still holds any personal value. */
+function hasDataSql(group: Group, alias = ""): string {
+  return `(${groupColumns(group).map((column) => `${alias}${column} IS NOT NULL`).join(" OR ")})`;
 }
 
-interface VaultRow {
-  key_id: string;
-  nonce: string;
-  ciphertext: string;
-  not_after: string;
-  expires_at: string;
-  sealed_jti: string;
+/** SQL SET list nulling every personal column of the groups. */
+function clearSql(groups: readonly Group[]): string {
+  return groups.flatMap(groupColumns).map((column) => `${column} = NULL`).join(", ");
 }
 
-const TERMINAL_AT_SQL = `SELECT MIN(at) AS at FROM scrappy_shipment_audit
-  WHERE tenant_id = ? AND stage = ? AND order_id = ?
-    AND ((kind = 'transition' AND to_state = 'handed_off') OR (kind = 'pending-cancel' AND to_state = 'confirmed'))`;
+const ALL_EMPTY_SQL = GROUPS.map((group) => `NOT ${hasDataSql(group)}`).join(" AND ");
+
+/** Detach: only the unlinked facts remain (fact_id, tenant, stage, month, totals, zip3, region, country). */
+const DETACH_SET_SQL = [
+  "order_id", "ship_city", "ship_postal_code", "bill_city", "bill_postal_code", "order_kid", "bidx_kid",
+  "sealed_jti", "sealed_at", "erased_at", "time_scale", "rule_version",
+  ...GROUPS.flatMap((group) => [`${group}_ceiling`, `${group}_expires_at`, `${group}_floor_until`, `${group}_rule`]),
+].map((column) => `${column} = NULL`).join(", ");
+
+/**
+ * Normalization statements over `scopeSql` (with `scopeParams`): clear bidx_kid once both indexes
+ * are gone, then detach a publication row whose last group is gone. Preview rows stay linked until
+ * the purge deletes them whole with their marker at placed_at + the cutoff.
+ */
+function normalizeStatements(scopeSql: string, scopeParams: readonly unknown[]): QueryStatement[] {
+  return [
+    {
+      sql: `UPDATE order_contact_vault SET bidx_kid = NULL
+            WHERE ${scopeSql} AND bidx_kid IS NOT NULL AND email_bidx IS NULL AND phone_bidx IS NULL`,
+      params: [...scopeParams],
+    },
+    {
+      sql: `UPDATE order_contact_vault SET ${DETACH_SET_SQL}
+            WHERE ${scopeSql} AND stage = 'publication' AND order_id IS NOT NULL AND ${ALL_EMPTY_SQL}`,
+      params: [...scopeParams],
+    },
+  ];
+}
+
+type VaultRow = Record<string, unknown>;
+
+function text(row: VaultRow, column: string): string | null {
+  const value = row[column];
+  return typeof value === "string" ? value : null;
+}
+
+function rowHasData(row: VaultRow, group: Group): boolean {
+  return groupColumns(group).some((column) => row[column] !== null && row[column] !== undefined);
+}
+
+const ORDER_KEY = "order-contact" as const;
+const BIDX_KEY = "blind-index" as const;
+
+function keyContext(tenantId: string, stage: VaultStage, purpose: DataKeyPurpose): EncryptionContext {
+  return { tenantId, stage, purpose };
+}
 
-function binding(tenantId: string, stage: VaultStage, orderId: string, notAfter: string): VaultBinding {
-  return { purpose: "order-contact", tenantId, stage, recordId: orderId, notAfter };
+function fieldBinding(tenantId: string, stage: VaultStage, factId: string, kid: string, column: string, ceiling: string): FieldBinding {
+  return { purpose: ORDER_KEY, field: column.replace(/_ct$/, ""), tenantId, stage, recordId: factId, kid, notAfter: ceiling };
 }
 
 function requireBatch(db: Queryable): NonNullable<Queryable["batch"]> {
@@ -72,298 +141,1055 @@ function requireBatch(db: Queryable): NonNullable<Queryable["batch"]> {
   return db.batch.bind(db);
 }
 
-/** When the order became terminal, `null` when it is not terminal, or "unreadable". */
-async function terminalAt(db: Queryable, tenantId: string, stage: VaultStage, orderId: string, fulfillment: unknown): Promise<Date | null | "unreadable"> {
-  if (fulfillment !== "handed_off" && fulfillment !== "cancelled") return null;
-  const row = await db.first<{ at: unknown }>(TERMINAL_AT_SQL, tenantId, stage, orderId);
-  return readInstant(row?.at) ?? "unreadable";
+function randomHex128(): string {
+  return [...crypto.getRandomValues(new Uint8Array(16))].map((byte) => byte.toString(16).padStart(2, "0")).join("");
 }
 
-/** The order's not_after and expiry, derived from the order row alone. */
-export async function orderRetention(
-  db: Queryable,
+function sqlLiteral(value: string): string {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Order snapshot and effective expiry
+// ---------------------------------------------------------------------------------------------
+
+interface OrderSnapshot {
+  placedAtRaw: unknown;
+  fulfillmentState: unknown;
+  terminalAtRaw: string | null;
+  placedAt: Date;
+  terminalAt: Date | null;
+}
+
+function isTerminalState(state: unknown): boolean {
+  return state === "handed_off" || state === "cancelled";
+}
+
+/** Read placed_at and the stamp-tolerant terminal time; refusal codes when either is unreadable. */
+function orderTimes(placedAtRaw: unknown, fulfillmentState: unknown, terminalAtRaw: unknown): OrderSnapshot | "order-time-unreadable" {
+  const placedAt = readInstant(placedAtRaw);
+  if (!placedAt) return "order-time-unreadable";
+  const terminal = isTerminalState(fulfillmentState) ? readStampInstant(terminalAtRaw) : null;
+  if (isTerminalState(fulfillmentState) && !terminal) return "order-time-unreadable";
+  return {
+    placedAtRaw,
+    fulfillmentState,
+    terminalAtRaw: typeof terminalAtRaw === "string" ? terminalAtRaw : null,
+    placedAt,
+    terminalAt: terminal,
+  };
+}
+
+/**
+ * Re-derivation applies only non-floor rules (floors come from the row's immutable floor_until), so
+ * the tenant's regulated class is taken as true: any regulated non-floor rule then counts, which can
+ * only lengthen the derived expiry, never shorten it below what the rules require.
+ */
+function rederivationRules(tenantId: string, shipCountry: string | null, shipRegion: string | null, policy: RetentionPolicy) {
+  return applicableRules(tenantId, { shipCountry, shipRegion, regulated: true }, policy);
+}
+
+/** Each group's effective expiry now (shrink-only re-derivation of the row's values), or null. */
+function effectiveExpiries(
+  row: VaultRow,
+  tenantId: string,
+  stage: VaultStage,
+  order: { placedAt: Date; terminalAt: Date | null },
+  policy: RetentionPolicy,
+): Record<Group, string | null> {
+  const rules = rederivationRules(tenantId, text(row, "ship_country"), text(row, "ship_region"), policy);
+  const timeScale = Number(row.time_scale);
+  const out = {} as Record<Group, string | null>;
+  for (const group of GROUPS) {
+    const ceiling = text(row, `${group}_ceiling`);
+    const expiresAt = text(row, `${group}_expires_at`);
+    out[group] = ceiling && expiresAt
+      ? rederiveGroup({
+          group, ceiling, expiresAt, floorUntil: text(row, `${group}_floor_until`), timeScale, stage,
+          placedAt: order.placedAt, terminalAt: order.terminalAt, rules, policy,
+        })
+      : null;
+  }
+  return out;
+}
+
+interface GroupState {
+  sealed: boolean;
+  readable: boolean;
+  expiresAt: string | null;
+}
+
+function groupStates(
+  row: VaultRow,
+  tenantId: string,
+  stage: VaultStage,
+  order: { placedAt: Date; terminalAt: Date | null },
+  now: Date,
+  policy: RetentionPolicy,
+): Record<Group, GroupState> {
+  const effective = effectiveExpiries(row, tenantId, stage, order, policy);
+  const pastCutoff = stage === "preview" && now.getTime() >= Date.parse(previewDeleteAt(order.placedAt, policy));
+  const out = {} as Record<Group, GroupState>;
+  for (const group of GROUPS) {
+    const sealed = rowHasData(row, group);
+    const expiresAt = effective[group];
+    out[group] = {
+      sealed,
+      expiresAt,
+      readable: sealed && !pastCutoff && isGroupReadable(now, expiresAt, text(row, `${group}_ceiling`)),
+    };
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Opening
+// ---------------------------------------------------------------------------------------------
+
+export interface ReadableContact {
+  customer?: { name?: string; email?: string; phone?: string };
+  shipTo?: ContactAddress;
+  billTo?: ContactAddress;
+}
+
+export interface GroupView {
+  expiresAt: string;
+  rule: string | null;
+}
+
+/**
+ * Open every sealed field of the given groups. Null when any field fails to authenticate (moved,
+ * swapped or tampered) or a required value is missing: the record then reads as not found.
+ */
+async function openGroups(
+  key: CryptoKey,
+  row: VaultRow,
   tenantId: string,
   stage: VaultStage,
-  orderId: string,
-): Promise<{ notAfter: string; expiresAt: string } | "order-unknown" | "order-time-unreadable"> {
-  const order = await db.first<OrderRow>(
-    `SELECT placed_at, fulfillment_state FROM scrappy_commerce_orders WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
-    tenantId, stage, orderId,
+  groups: readonly Group[],
+): Promise<ReadableContact | null> {
+  const factId = text(row, "fact_id");
+  const kid = text(row, "order_kid");
+  if (!factId || !kid) return null;
+  const opened = new Map<string, string>();
+  for (const group of groups) {
+    const ceiling = text(row, `${group}_ceiling`);
+    if (!ceiling) return null;
+    for (const column of LAYOUT[group].sealed) {
+      const sealed = text(row, column);
+      if (sealed === null) continue;
+      const value = await openField(key, fieldBinding(tenantId, stage, factId, kid, column, ceiling), sealed);
+      if (value === null) return null;
+      opened.set(column, value);
+    }
+  }
+  const contact: ReadableContact = {};
+  const customer: { name?: string; email?: string; phone?: string } = {};
+  if (groups.includes("identity")) {
+    const name = opened.get("name_ct");
+    if (name === undefined) return null;
+    customer.name = name;
+  }
+  if (groups.includes("email")) {
+    const email = opened.get("email_ct");
+    if (email === undefined) return null;
+    customer.email = email;
+  }
+  if (groups.includes("phone")) {
+    const phone = opened.get("phone_ct");
+    if (phone === undefined) return null;
+    customer.phone = phone;
+  }
+  if (Object.keys(customer).length > 0) contact.customer = customer;
+  for (const [group, prefix, member] of [["ship", "ship", "shipTo"], ["bill", "bill", "billTo"]] as const) {
+    if (!groups.includes(group)) continue;
+    const line1 = opened.get(`${prefix}_line1_ct`);
+    const city = text(row, `${prefix}_city`);
+    const country = text(row, `${prefix}_country`);
+    if (line1 === undefined || city === null || country === null) return null;
+    const address: Record<string, string> = { line1, city, country };
+    const name = opened.get(`${prefix}_name_ct`);
+    const company = opened.get(`${prefix}_company_ct`);
+    const line2 = opened.get(`${prefix}_line2_ct`);
+    const region = text(row, `${prefix}_region`);
+    const postalCode = text(row, `${prefix}_postal_code`);
+    if (name !== undefined) address.name = name;
+    if (company !== undefined) address.company = company;
+    if (line2 !== undefined) address.line2 = line2;
+    if (region !== null) address.region = region;
+    if (postalCode !== null) address.postalCode = postalCode;
+    contact[member] = address as unknown as ContactAddress;
+  }
+  return contact;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Seal
+// ---------------------------------------------------------------------------------------------
+
+export type SealOutcome =
+  | { ok: true; status: 200; duplicate: boolean }
+  | {
+      ok: false;
+      status: 401 | 409 | 410 | 503;
+      reason: "replay" | "order-unknown" | "order-time-unreadable" | "contact-conflict" | "contact-expired" | "contact-erased" | "vault-key-unavailable";
+    };
+
+export interface SealInput {
+  tenantId: string;
+  stage: VaultStage;
+  command: OrderContactCommand;
+  issuer: string;
+  jti: string;
+  /** isRegulatedTenant for the routed tenant. */
+  regulated: boolean;
+  now: Date;
+  policy?: RetentionPolicy;
+}
+
+interface SealSnapshot extends OrderSnapshot {
+  marked: boolean;
+}
+
+async function sealSnapshot(db: Queryable, tenantId: string, stage: VaultStage, orderId: string): Promise<SealSnapshot | "order-unknown" | "order-time-unreadable"> {
+  const order = await db.first<{ placed_at: unknown; fulfillment_state: unknown; terminal_at: unknown; marked: number }>(
+    `SELECT o.placed_at, o.fulfillment_state, (${TERMINAL_AT_SQL}) AS terminal_at,
+            EXISTS (SELECT 1 FROM order_contact_markers m WHERE m.tenant_id = o.tenant_id AND m.stage = o.stage AND m.order_id = o.order_id) AS marked
+     FROM scrappy_commerce_orders o WHERE o.tenant_id = ? AND o.stage = ? AND o.order_id = ?`,
+    tenantId, stage, orderId, tenantId, stage, orderId,
   );
   if (!order) return "order-unknown";
-  const placed = readInstant(order.placed_at);
-  if (!placed) return "order-time-unreadable";
-  const terminal = await terminalAt(db, tenantId, stage, orderId, order.fulfillment_state);
-  if (terminal === "unreadable") return "order-time-unreadable";
-  const notAfter = notAfterFrom(placed);
-  return { notAfter, expiresAt: expiresAtFor(notAfter, terminal) };
+  const times = orderTimes(order.placed_at, order.fulfillment_state, order.terminal_at);
+  if (times === "order-time-unreadable") return times;
+  return { ...times, marked: Number(order.marked) === 1 };
+}
+
+const SEALED_VALUES: ReadonlyArray<[string, (command: OrderContactCommand) => string | undefined]> = [
+  ["name_ct", (c) => c.customer.name],
+  ["company_ct", () => undefined],
+  ["email_ct", (c) => c.customer.email],
+  ["phone_ct", (c) => c.customer.phone],
+  ["ship_name_ct", (c) => c.shipTo.name],
+  ["ship_company_ct", (c) => c.shipTo.company],
+  ["ship_line1_ct", (c) => c.shipTo.line1],
+  ["ship_line2_ct", (c) => c.shipTo.line2],
+  ["bill_name_ct", (c) => c.billTo.name],
+  ["bill_company_ct", (c) => c.billTo.company],
+  ["bill_line1_ct", (c) => c.billTo.line1],
+  ["bill_line2_ct", (c) => c.billTo.line2],
+];
+
+function groupOfColumn(column: string): Group {
+  for (const group of GROUPS) if (LAYOUT[group].sealed.includes(column)) return group;
+  throw new Error("vault layout");
+}
+
+function placedMonth(placedAt: Date): string {
+  return `${placedAt.getUTCFullYear()}${String(placedAt.getUTCMonth() + 1).padStart(2, "0")}`;
 }
 
 /** Seal one order's contact from a verified contact command. */
-export async function sealOrderContact(
-  db: Queryable,
-  keyring: VaultKeyring | null,
-  input: { tenantId: string; stage: VaultStage; command: OrderContactCommand; issuer: string; jti: string; now: Date },
-): Promise<SealOutcome> {
+export async function sealOrderContact(db: Queryable, kms: KmsClient, input: SealInput): Promise<SealOutcome> {
+  try {
+    return await sealAttempt(db, kms, input, 3);
+  } catch (error) {
+    if (error instanceof VaultKeyUnavailableError) return { ok: false, status: 503, reason: "vault-key-unavailable" };
+    throw error;
+  }
+}
+
+async function replayed(db: Queryable, tenantId: string, stage: VaultStage, issuer: string, jti: string): Promise<boolean> {
+  return (await db.first(
+    `SELECT 1 AS seen FROM scrappy_caller_replay WHERE tenant_id = ? AND stage = ? AND issuer = ? AND jti = ?`,
+    tenantId, stage, issuer, jti,
+  )) !== null;
+}
+
+async function sealAttempt(db: Queryable, kms: KmsClient, input: SealInput, attempts: number): Promise<SealOutcome> {
   const { tenantId, stage, command, issuer, jti, now } = input;
+  const policy = input.policy ?? RETENTION_POLICY;
   const orderId = command.orderId;
   const nowIso = now.toISOString();
   const sealedJti = `${issuer}:${jti}`;
-  const seen = await db.first(
-    `SELECT 1 AS seen FROM scrappy_caller_replay WHERE tenant_id = ? AND stage = ? AND issuer = ? AND jti = ?`,
-    tenantId, stage, issuer, jti,
-  );
-  if (seen) return { ok: false, status: 401, reason: "replay" };
-  const retention = await orderRetention(db, tenantId, stage, orderId);
-  if (retention === "order-unknown") return { ok: false, status: 409, reason: "order-unknown" };
-  if (retention === "order-time-unreadable") return { ok: false, status: 409, reason: "order-time-unreadable" };
-  const existing = await classifyExisting(db, keyring, tenantId, stage, command, sealedJti);
+  if (await replayed(db, tenantId, stage, issuer, jti)) return { ok: false, status: 401, reason: "replay" };
+  const snapshot = await sealSnapshot(db, tenantId, stage, orderId);
+  if (snapshot === "order-unknown") return { ok: false, status: 409, reason: "order-unknown" };
+  if (snapshot === "order-time-unreadable") return { ok: false, status: 409, reason: "order-time-unreadable" };
+  const existing = await classifyExisting(db, kms, input, snapshot, sealedJti, policy);
   if (existing) return existing;
-  if (nowIso >= retention.expiresAt) return { ok: false, status: 410, reason: "contact-expired" };
 
-  let sealed;
-  try {
-    sealed = await sealVaultRecord(keyring, binding(tenantId, stage, orderId, retention.notAfter), orderContactPlaintext(command));
-  } catch (error) {
-    if (error instanceof VaultKeyUnavailableError) return { ok: false, status: 503, reason: "vault-key-unavailable" };
-    throw error;
+  const retention = await sealRetention({
+    stage, placedAt: snapshot.placedAt, terminalAt: snapshot.terminalAt,
+    shipCountry: command.shipTo.country, shipRegion: command.shipTo.region ?? null,
+    regulated: input.regulated, tenantId, now, policy,
+  });
+  if (retention.kind === "refused") {
+    return retention.reason === "order-time-unreadable"
+      ? { ok: false, status: 409, reason: "order-time-unreadable" }
+      : { ok: false, status: 410, reason: "contact-expired" };
   }
+
+  const orderCtx = keyContext(tenantId, stage, ORDER_KEY);
+  const bidxCtx = keyContext(tenantId, stage, BIDX_KEY);
+  const orderKey = await activeKey(db, kms, orderCtx, now);
+  const bidxKey = await activeKey(db, kms, bidxCtx, now);
+
+  const factId = randomHex128();
+  // A group whose expiry has already passed is never written: only live groups are sealed.
+  const live = (group: Group): boolean => retention.groups[group].expiresAt > nowIso;
+  const ifLive = <T>(group: Group, value: T): T | null => (live(group) ? value : null);
+  const columns: Array<[string, unknown]> = [
+    ["fact_id", factId], ["tenant_id", tenantId], ["stage", stage], ["order_id", orderId],
+    ["placed_month", placedMonth(snapshot.placedAt)],
+    ["ship_region", command.shipTo.region ?? null], ["ship_country", command.shipTo.country],
+    ["ship_zip3", zip3(command.shipTo.postalCode, command.shipTo.country)],
+    ["bill_region", command.billTo.region ?? null], ["bill_country", command.billTo.country],
+    ["bill_zip3", zip3(command.billTo.postalCode, command.billTo.country)],
+    ["time_scale", retention.timeScale], ["rule_version", retention.ruleVersion],
+    ["order_kid", orderKey.kid], ["bidx_kid", bidxKey.kid], ["sealed_at", nowIso], ["sealed_jti", sealedJti],
+    ["ship_city", ifLive("ship", command.shipTo.city)], ["ship_postal_code", ifLive("ship", command.shipTo.postalCode ?? null)],
+    ["bill_city", ifLive("bill", command.billTo.city)], ["bill_postal_code", ifLive("bill", command.billTo.postalCode ?? null)],
+  ];
+  for (const [column, pick] of SEALED_VALUES) {
+    const value = pick(command);
+    const group = groupOfColumn(column);
+    columns.push([
+      column,
+      value === undefined || !live(group)
+        ? null
+        : await sealField(orderKey.key, fieldBinding(tenantId, stage, factId, orderKey.kid, column, retention.groups[group].ceiling), value),
+    ]);
+  }
+  const email = live("email") ? normalizeEmail(command.customer.email) : null;
+  const phone = live("phone") ? normalizePhone(command.customer.phone) : null;
+  columns.push(["email_bidx", email === null ? null : await blindIndex(bidxKey.key, email)]);
+  columns.push(["phone_bidx", phone === null ? null : await blindIndex(bidxKey.key, phone)]);
+  if (email === null && phone === null) columns.find(([column]) => column === "bidx_kid")![1] = null;
+  let latest = "";
+  for (const group of GROUPS) {
+    const held = retention.groups[group];
+    columns.push([`${group}_ceiling`, held.ceiling], [`${group}_expires_at`, held.expiresAt], [`${group}_floor_until`, held.floorUntil], [`${group}_rule`, held.rule]);
+    if (held.expiresAt > latest) latest = held.expiresAt;
+  }
+
+  const vaultRowSql = `SELECT 1 FROM order_contact_vault WHERE tenant_id = ? AND stage = ? AND order_id = ? AND sealed_jti = ?`;
+  const vaultRowParams = [tenantId, stage, orderId, sealedJti];
   const statements: QueryStatement[] = [
+    ...orderKey.pending,
+    ...bidxKey.pending,
     {
-      sql: `INSERT INTO order_contact_vault
-              (tenant_id, stage, order_id, key_id, nonce, ciphertext, not_after, expires_at, sealed_at, sealed_jti)
-            SELECT ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
-            WHERE EXISTS (SELECT 1 FROM scrappy_commerce_orders WHERE tenant_id = ? AND stage = ? AND order_id = ?)
-              AND NOT EXISTS (SELECT 1 FROM order_contact_tombstones WHERE tenant_id = ? AND stage = ? AND order_id = ?)
+      sql: `INSERT INTO order_contact_vault (${columns.map(([column]) => column).join(", ")}, currency, order_total_minor, item_count)
+            SELECT ${columns.map(() => "?").join(", ")}, o.currency, o.amount_minor,
+                   (SELECT SUM(a.quantity) FROM scrappy_allocations a WHERE a.tenant_id = o.tenant_id AND a.stage = o.stage AND a.order_id = o.order_id)
+            FROM scrappy_commerce_orders o
+            WHERE o.tenant_id = ? AND o.stage = ? AND o.order_id = ? AND o.placed_at IS ? AND o.fulfillment_state IS ?
+              AND (${TERMINAL_AT_SQL}) IS ?
+              AND NOT EXISTS (SELECT 1 FROM order_contact_markers m WHERE m.tenant_id = ? AND m.stage = ? AND m.order_id = ?)
+              AND NOT EXISTS (SELECT 1 FROM order_contact_vault v WHERE v.tenant_id = ? AND v.stage = ? AND v.order_id = ?)
+              AND EXISTS (SELECT 1 FROM contact_vault_data_keys k WHERE k.tenant_id = ? AND k.stage = ? AND k.purpose = ? AND k.kid = ?)
+              AND EXISTS (SELECT 1 FROM contact_vault_data_keys k WHERE k.tenant_id = ? AND k.stage = ? AND k.purpose = ? AND k.kid = ?)
               AND ? < ?
-            ON CONFLICT (tenant_id, stage, order_id) DO NOTHING`,
+            ON CONFLICT DO NOTHING`,
       params: [
-        tenantId, stage, orderId, sealed.keyId, sealed.nonce, sealed.ciphertext, retention.notAfter, retention.expiresAt, nowIso, sealedJti,
+        ...columns.map(([, value]) => value),
+        tenantId, stage, orderId, snapshot.placedAtRaw, snapshot.fulfillmentState,
+        tenantId, stage, orderId, snapshot.terminalAtRaw,
         tenantId, stage, orderId,
         tenantId, stage, orderId,
-        nowIso, retention.expiresAt,
+        tenantId, stage, ORDER_KEY, orderKey.kid,
+        tenantId, stage, BIDX_KEY, bidxKey.kid,
+        nowIso, latest,
       ],
     },
+    {
+      sql: `INSERT INTO order_contact_markers (tenant_id, stage, order_id)
+            SELECT ?, ?, ? WHERE EXISTS (${vaultRowSql})
+            ON CONFLICT DO NOTHING`,
+      params: [tenantId, stage, orderId, ...vaultRowParams],
+    },
     {
       sql: `INSERT INTO scrappy_caller_replay (tenant_id, stage, issuer, jti, seen_at)
-            SELECT ?, ?, ?, ?, ?
-            WHERE EXISTS (SELECT 1 FROM order_contact_vault WHERE tenant_id = ? AND stage = ? AND order_id = ? AND sealed_jti = ?)`,
-      params: [tenantId, stage, issuer, jti, nowIso, tenantId, stage, orderId, sealedJti],
+            SELECT ?, ?, ?, ?, ? WHERE EXISTS (${vaultRowSql})`,
+      params: [tenantId, stage, issuer, jti, nowIso, ...vaultRowParams],
     },
   ];
+  if (orderKey.pending.length > 0) {
+    statements.push(cleanupStatement(orderCtx, orderKey.kid,
+      `SELECT 1 FROM order_contact_vault WHERE tenant_id = ? AND stage = ? AND order_kid = ?`, [tenantId, stage, orderKey.kid]));
+  }
+  if (bidxKey.pending.length > 0) {
+    statements.push(cleanupStatement(bidxCtx, bidxKey.kid,
+      `SELECT 1 FROM order_contact_vault WHERE tenant_id = ? AND stage = ? AND bidx_kid = ?
+       UNION ALL SELECT 1 FROM contact_messages WHERE tenant_id = ? AND stage = ? AND bidx_kid = ?`,
+      [tenantId, stage, bidxKey.kid, tenantId, stage, bidxKey.kid]));
+  }
   try {
     await requireBatch(db)(statements);
   } catch (error) {
     // The only conflict the batch can raise is the replay key: this jti committed concurrently
     // elsewhere. Anything else is a fault the sender must retry, never a replay.
-    const replayed = await db.first(
-      `SELECT 1 AS seen FROM scrappy_caller_replay WHERE tenant_id = ? AND stage = ? AND issuer = ? AND jti = ?`,
-      tenantId, stage, issuer, jti,
-    );
-    if (replayed) return { ok: false, status: 401, reason: "replay" };
+    if (await replayed(db, tenantId, stage, issuer, jti)) return { ok: false, status: 401, reason: "replay" };
     throw error;
   }
-  const after = await classifyExisting(db, keyring, tenantId, stage, command, sealedJti);
-  if (after) return after;
-  const again = await orderRetention(db, tenantId, stage, orderId);
+  const again = await sealSnapshot(db, tenantId, stage, orderId);
   if (again === "order-unknown") return { ok: false, status: 409, reason: "order-unknown" };
-  return { ok: false, status: 410, reason: "contact-expired" };
+  if (again === "order-time-unreadable") return { ok: false, status: 409, reason: "order-time-unreadable" };
+  const after = await classifyExisting(db, kms, input, again, sealedJti, policy);
+  if (after) return after;
+  // Nothing committed: the order's retention snapshot or the active key changed underneath. Re-read
+  // and re-seal, bounded.
+  if (attempts > 1) return sealAttempt(db, kms, input, attempts - 1);
+  throw new Error("contact-retention-changed");
 }
 
-/** Classify an order that already has a vault row or a tombstone, or null when it has neither. */
+/**
+ * Classify an order that already has a linked vault row or a marker, or null when it has neither.
+ * A linked row with every group sealed and readable answers duplicate or conflict; one with any
+ * group cleared or expired, or a marker without a linked row, answers 410 and never refills.
+ */
 async function classifyExisting(
   db: Queryable,
-  keyring: VaultKeyring | null,
-  tenantId: string,
-  stage: VaultStage,
-  command: OrderContactCommand,
+  kms: KmsClient,
+  input: SealInput,
+  snapshot: SealSnapshot,
   sealedJti: string,
+  policy: RetentionPolicy,
 ): Promise<SealOutcome | null> {
+  const { tenantId, stage, command, now } = input;
   const row = await db.first<VaultRow>(
-    `SELECT key_id, nonce, ciphertext, not_after, expires_at, sealed_jti FROM order_contact_vault
-     WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
+    `SELECT * FROM order_contact_vault WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
     tenantId, stage, command.orderId,
   );
-  if (row) {
-    if (row.sealed_jti === sealedJti) return { ok: true, status: 200, duplicate: false };
-    let stored: unknown | null;
-    try {
-      stored = await openVaultRecord(keyring, binding(tenantId, stage, command.orderId, row.not_after), {
-        keyId: row.key_id, nonce: row.nonce, ciphertext: row.ciphertext,
-      });
-    } catch (error) {
-      if (error instanceof VaultKeyUnavailableError) return { ok: false, status: 503, reason: "vault-key-unavailable" };
-      throw error;
-    }
-    return stored !== null && sameOrderContact(stored, orderContactPlaintext(command))
-      ? { ok: true, status: 200, duplicate: true }
-      : { ok: false, status: 409, reason: "contact-conflict" };
+  if (!row) return snapshot.marked ? { ok: false, status: 410, reason: "contact-expired" } : null;
+  // This command's own seal (the replay row committed with it, so this is only ever the post-batch read).
+  if (row.sealed_jti === sealedJti) return { ok: true, status: 200, duplicate: false };
+  const states = groupStates(row, tenantId, stage, snapshot, now, policy);
+  if (GROUPS.some((group) => !states[group].readable)) {
+    return { ok: false, status: 410, reason: row.erased_at ? "contact-erased" : "contact-expired" };
   }
-  const tomb = await db.first<{ reason: string }>(
-    `SELECT reason FROM order_contact_tombstones WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
-    tenantId, stage, command.orderId,
+  const kid = text(row, "order_kid");
+  const key = kid ? await keyForKid(db, kms, keyContext(tenantId, stage, ORDER_KEY), kid) : null;
+  if (!key) return { ok: false, status: 503, reason: "vault-key-unavailable" };
+  const stored = await openGroups(key, row, tenantId, stage, GROUPS);
+  return stored !== null && sameOrderContact(stored, orderContactPlaintext(command))
+    ? { ok: true, status: 200, duplicate: true }
+    : { ok: false, status: 409, reason: "contact-conflict" };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Read and list
+// ---------------------------------------------------------------------------------------------
+
+export type ReadOutcome =
+  | { ok: true; contact: ReadableContact; expiresAt: string; groups: Partial<Record<Group, GroupView>> }
+  | { ok: false; status: 410; reason: "contact-expired" }
+  | { ok: false; status: 404 | 429 | 503; reason: "not-found" | "quota" | "audit-unavailable" | "vault-key-unavailable" };
+
+/** TERMINAL_AT_SQL correlated to the order row aliased `alias` instead of bound parameters. */
+function correlatedTerminalSql(alias: string): string {
+  const sql = TERMINAL_AT_SQL.replace(
+    "tenant_id = ? AND stage = ? AND order_id = ?",
+    `tenant_id = ${alias}.tenant_id AND stage = ${alias}.stage AND order_id = ${alias}.order_id`,
   );
-  if (tomb) return { ok: false, status: 410, reason: tomb.reason === "erased" ? "contact-erased" : "contact-expired" };
-  return null;
+  if (sql === TERMINAL_AT_SQL || sql.includes("?")) throw new Error("vault: terminal-time SQL shape changed");
+  return sql;
+}
+
+const ORDER_JOIN_SELECT = `SELECT v.*, o.placed_at AS order_placed_at, o.fulfillment_state AS order_fulfillment_state,
+    (${correlatedTerminalSql("o")}) AS order_terminal_at
+  FROM scrappy_commerce_orders o
+  JOIN order_contact_vault v ON v.tenant_id = o.tenant_id AND v.stage = o.stage AND v.order_id = o.order_id`;
+
+interface Viewable {
+  groups: Group[];
+  views: Partial<Record<Group, GroupView>>;
+  expiresAt: string;
 }
 
-/** Read one order's contact. The audit row commits before anything is decrypted. */
+/** The groups of a joined row readable now, or null when none is (or the order times are unreadable). */
+function viewable(row: VaultRow, tenantId: string, stage: VaultStage, now: Date, policy: RetentionPolicy): Viewable | null {
+  const times = orderTimes(row.order_placed_at, row.order_fulfillment_state, row.order_terminal_at);
+  if (times === "order-time-unreadable") return null;
+  const states = groupStates(row, tenantId, stage, times, now, policy);
+  const groups = GROUPS.filter((group) => states[group].readable);
+  if (groups.length === 0) return null;
+  const views: Partial<Record<Group, GroupView>> = {};
+  let earliest: string | null = null;
+  for (const group of groups) {
+    const ceiling = text(row, `${group}_ceiling`)!;
+    const effective = states[group].expiresAt!;
+    const expiresAt = effective < ceiling ? effective : ceiling;
+    views[group] = { expiresAt, rule: text(row, `${group}_rule`) };
+    if (earliest === null || expiresAt < earliest) earliest = expiresAt;
+  }
+  return { groups, views, expiresAt: earliest! };
+}
+
+/** True when a preview order is at or past placed_at + the preview cutoff (nothing is admitted then). */
+async function pastPreviewCutoff(db: Queryable, tenantId: string, stage: VaultStage, orderId: string, now: Date, policy: RetentionPolicy): Promise<boolean> {
+  if (stage !== "preview") return false;
+  const order = await db.first<{ placed_at: unknown }>(
+    `SELECT placed_at FROM scrappy_commerce_orders WHERE tenant_id = ? AND stage = ? AND order_id = ?`, tenantId, stage, orderId,
+  );
+  const placedAt = order ? readInstant(order.placed_at) : null;
+  return placedAt !== null && now.getTime() >= Date.parse(previewDeleteAt(placedAt, policy));
+}
+
+/**
+ * Read one order's contact: only the groups readable now. A preview order at or past its cutoff
+ * answers 410 with zero writes; otherwise the audit row commits before any decrypt.
+ */
 export async function readOrderContact(
   db: Queryable,
-  keyring: VaultKeyring | null,
-  input: { tenantId: string; stage: VaultStage; orderId: string; actor: ContactActor; auditId: string; now: Date },
+  kms: KmsClient,
+  input: { tenantId: string; stage: VaultStage; orderId: string; actor: ContactActor; auditId: string; now: Date; policy?: RetentionPolicy },
 ): Promise<ReadOutcome> {
   const { tenantId, stage, orderId, actor, auditId, now } = input;
+  const policy = input.policy ?? RETENTION_POLICY;
+  if (await pastPreviewCutoff(db, tenantId, stage, orderId, now, policy)) return { ok: false, status: 410, reason: "contact-expired" };
   const admitted = await admitAudit(db, auditStatement({
     auditId, tenantId, stage, recordKind: "order-contact", recordId: orderId, actor, action: "read", now,
   }));
   if (admitted === "quota") return { ok: false, status: 429, reason: "quota" };
   if (admitted === "unavailable") return { ok: false, status: 503, reason: "audit-unavailable" };
-  const row = await db.first<VaultRow>(
-    `SELECT key_id, nonce, ciphertext, not_after, expires_at, sealed_jti FROM order_contact_vault
-     WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
-    tenantId, stage, orderId,
+  const row = await db.first<VaultRow>(`${ORDER_JOIN_SELECT} WHERE o.tenant_id = ? AND o.stage = ? AND o.order_id = ?`, tenantId, stage, orderId);
+  if (!row) return { ok: false, status: 404, reason: "not-found" };
+  const view = viewable(row, tenantId, stage, now, policy);
+  if (!view) return { ok: false, status: 404, reason: "not-found" };
+  try {
+    const kid = text(row, "order_kid");
+    const key = kid ? await keyForKid(db, kms, keyContext(tenantId, stage, ORDER_KEY), kid) : null;
+    if (!key) return { ok: false, status: 404, reason: "not-found" };
+    const contact = await openGroups(key, row, tenantId, stage, view.groups);
+    if (!contact) return { ok: false, status: 404, reason: "not-found" };
+    return { ok: true, contact, expiresAt: view.expiresAt, groups: view.views };
+  } catch (error) {
+    if (error instanceof VaultKeyUnavailableError) return { ok: false, status: 503, reason: "vault-key-unavailable" };
+    throw error;
+  }
+}
+
+export interface ListedContact {
+  orderId: string;
+  contact: ReadableContact;
+  expiresAt: string;
+  groups: Partial<Record<Group, GroupView>>;
+}
+
+export type ListOutcome =
+  | { ok: true; contacts: ListedContact[] }
+  | { ok: false; status: 403 | 429 | 503; reason: "support-read-required" | "quota" | "audit-unavailable" | "vault-key-unavailable" };
+
+/**
+ * The Orders panel list: one query joining orders to the vault, one `list` audit row naming the
+ * order ids it returns and their count (before anything is decrypted), then local decryption under
+ * cached data keys. Owner only; at most {@link AUDIT_RECORD_IDS_MAX} records.
+ */
+export async function listOrderContacts(
+  db: Queryable,
+  kms: KmsClient,
+  input: { tenantId: string; stage: VaultStage; actor: ContactActor; auditId: string; now: Date; limit?: number; policy?: RetentionPolicy },
+): Promise<ListOutcome> {
+  const { tenantId, stage, actor, auditId, now } = input;
+  const policy = input.policy ?? RETENTION_POLICY;
+  if (actor.role !== "owner") return { ok: false, status: 403, reason: "support-read-required" };
+  const limit = Math.max(1, Math.min(AUDIT_RECORD_IDS_MAX, Math.floor(input.limit ?? 100)));
+  const rows = await db.all<VaultRow>(
+    `${ORDER_JOIN_SELECT} WHERE o.tenant_id = ? AND o.stage = ? ORDER BY o.placed_at DESC, o.order_id LIMIT ?`,
+    tenantId, stage, limit,
   );
-  if (!row || !isReadable(now, row.expires_at, row.not_after)) return { ok: false, status: 404, reason: "not-found" };
-  let opened: unknown | null;
+  const candidates = rows.flatMap((row) => {
+    const view = viewable(row, tenantId, stage, now, policy);
+    return view ? [{ row, view }] : [];
+  });
+  const admitted = await admitAudit(db, auditStatement({
+    auditId, tenantId, stage, recordKind: "order-contact", recordId: auditRecordIds(candidates.map(({ row }) => String(row.order_id))),
+    recordCount: candidates.length, actor, action: "list", now,
+  }));
+  if (admitted === "quota") return { ok: false, status: 429, reason: "quota" };
+  if (admitted === "unavailable") return { ok: false, status: 503, reason: "audit-unavailable" };
+  const contacts: ListedContact[] = [];
   try {
-    opened = await openVaultRecord(keyring, binding(tenantId, stage, orderId, row.not_after), {
-      keyId: row.key_id, nonce: row.nonce, ciphertext: row.ciphertext,
-    });
+    const keys = new Map<string, CryptoKey | null>();
+    for (const { row, view } of candidates) {
+      const kid = text(row, "order_kid");
+      if (!kid) continue;
+      if (!keys.has(kid)) keys.set(kid, await keyForKid(db, kms, keyContext(tenantId, stage, ORDER_KEY), kid));
+      const key = keys.get(kid);
+      if (!key) continue;
+      const contact = await openGroups(key, row, tenantId, stage, view.groups);
+      if (!contact) continue;
+      contacts.push({ orderId: String(row.order_id), contact, expiresAt: view.expiresAt, groups: view.views });
+    }
   } catch (error) {
     if (error instanceof VaultKeyUnavailableError) return { ok: false, status: 503, reason: "vault-key-unavailable" };
     throw error;
   }
-  if (opened === null || typeof opened !== "object") return { ok: false, status: 404, reason: "not-found" };
-  return { ok: true, contact: opened as OrderContact, expiresAt: row.expires_at < row.not_after ? row.expires_at : row.not_after };
+  return { ok: true, contacts };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Search
+// ---------------------------------------------------------------------------------------------
+
+export type SearchQuery = { email: string } | { phone: string };
+
+export type SearchOutcome =
+  | { ok: true; orderIds: string[] }
+  | { ok: false; status: 400 | 403 | 429 | 503; reason: "malformed" | "support-read-required" | "quota" | "audit-unavailable" | "vault-key-unavailable" };
+
+/** A search body: exactly `{email}` or exactly `{phone}`, a bounded string. Null otherwise. */
+export function readSearchQuery(body: unknown): SearchQuery | null {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return null;
+  const keys = Object.keys(body);
+  if (keys.length !== 1) return null;
+  const record = body as Record<string, unknown>;
+  if (keys[0] === "email" && typeof record.email === "string" && record.email.length <= 254) return { email: record.email };
+  if (keys[0] === "phone" && typeof record.phone === "string" && record.phone.length <= 40) return { phone: record.phone };
+  return null;
+}
+
+/**
+ * Owner exact-match search by email or phone: the normalized value's blind index under every
+ * blind-index key the tenant still holds, matched against linked rows of the routed tenant and
+ * stage whose group is readable now, at most {@link AUDIT_RECORD_IDS_MAX}. The audit row stores the
+ * action, the matched order ids and their count, never the searched value.
+ */
+export async function searchOrderContacts(
+  db: Queryable,
+  kms: KmsClient,
+  input: { tenantId: string; stage: VaultStage; actor: ContactActor; auditId: string; now: Date; query: SearchQuery },
+): Promise<SearchOutcome> {
+  const { tenantId, stage, actor, auditId, now, query } = input;
+  if (actor.role !== "owner") return { ok: false, status: 403, reason: "support-read-required" };
+  const isEmail = "email" in query;
+  const normalized = isEmail ? normalizeEmail(query.email) : normalizePhone(query.phone);
+  if (normalized === null) return { ok: false, status: 400, reason: "malformed" };
+  const group: Group = isEmail ? "email" : "phone";
+  const column = isEmail ? "email_bidx" : "phone_bidx";
+  const pairs: Array<[string, string]> = [];
+  try {
+    const kids = await db.all<{ kid: string }>(
+      `SELECT kid FROM contact_vault_data_keys WHERE tenant_id = ? AND stage = ? AND purpose = ? ORDER BY created_at`,
+      tenantId, stage, BIDX_KEY,
+    );
+    for (const { kid } of kids) {
+      const key = await keyForKid(db, kms, keyContext(tenantId, stage, BIDX_KEY), kid);
+      if (key) pairs.push([kid, await blindIndex(key, normalized)]);
+    }
+  } catch (error) {
+    if (error instanceof VaultKeyUnavailableError) return { ok: false, status: 503, reason: "vault-key-unavailable" };
+    throw error;
+  }
+  let orderIds: string[] = [];
+  if (pairs.length > 0) {
+    const rows = await db.all<{ order_id: string; expires_at: string | null; ceiling: string | null }>(
+      `SELECT order_id, ${group}_expires_at AS expires_at, ${group}_ceiling AS ceiling FROM order_contact_vault
+       WHERE tenant_id = ? AND stage = ? AND order_id IS NOT NULL AND ${group}_expires_at > ? AND ${group}_ceiling > ?
+         AND (${pairs.map(() => `(bidx_kid = ? AND ${column} = ?)`).join(" OR ")})
+       ORDER BY order_id LIMIT ?`,
+      tenantId, stage, now.toISOString(), now.toISOString(), ...pairs.flat(), AUDIT_RECORD_IDS_MAX,
+    );
+    orderIds = rows.filter((row) => isGroupReadable(now, row.expires_at, row.ceiling)).map((row) => row.order_id);
+  }
+  const admitted = await admitAudit(db, auditStatement({
+    auditId, tenantId, stage, recordKind: "order-contact", recordId: auditRecordIds(orderIds), recordCount: orderIds.length, actor, action: "search", now,
+  }));
+  if (admitted === "quota") return { ok: false, status: 429, reason: "quota" };
+  if (admitted === "unavailable") return { ok: false, status: 503, reason: "audit-unavailable" };
+  return { ok: true, orderIds };
 }
 
-/** Erase one order's contact: audit, tombstone and delete in one batch. */
+// ---------------------------------------------------------------------------------------------
+// Erase
+// ---------------------------------------------------------------------------------------------
+
+export type EraseOutcome =
+  | { ok: true; groups: Group[] }
+  | { ok: false; status: 404 | 429 | 503; reason: "not-found" | "quota" | "audit-unavailable" }
+  | { ok: false; status: 409; reason: "retention-hold"; group: Group; holdUntil: string };
+
+/** Erase-request groups: a non-empty list of distinct known groups, or null. */
+export function readEraseGroups(value: unknown): Group[] | null {
+  if (!Array.isArray(value) || value.length === 0 || value.length > GROUPS.length) return null;
+  if (!value.every((group) => typeof group === "string" && (GROUPS as readonly string[]).includes(group))) return null;
+  if (new Set(value).size !== value.length) return null;
+  return value as Group[];
+}
+
+/**
+ * Erase field groups of one order's contact. `groups` defaults to every group still holding data
+ * that no floor holds. A named group under a floor answers 409 retention-hold with its hold-until
+ * date, with no audit row and no change. Otherwise audit, clearing and detach commit together; the
+ * marker stays, so a later resend answers 410.
+ */
 export async function eraseOrderContact(
   db: Queryable,
-  input: { tenantId: string; stage: VaultStage; orderId: string; actor: ContactActor; auditId: string; now: Date },
+  input: { tenantId: string; stage: VaultStage; orderId: string; actor: ContactActor; auditId: string; now: Date; groups?: readonly Group[] },
 ): Promise<EraseOutcome> {
   const { tenantId, stage, orderId, actor, auditId, now } = input;
-  const nowIso = now.toISOString();
-  const exists = await db.first(
-    `SELECT 1 AS present FROM order_contact_vault WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
-    tenantId, stage, orderId,
+  const row = await db.first<VaultRow>(
+    `SELECT * FROM order_contact_vault WHERE tenant_id = ? AND stage = ? AND order_id = ?`, tenantId, stage, orderId,
   );
-  if (!exists) return { ok: false, status: 404, reason: "not-found" };
-  const rowSql = `SELECT 1 FROM order_contact_vault WHERE tenant_id = ? AND stage = ? AND order_id = ?`;
+  if (!row) return { ok: false, status: 404, reason: "not-found" };
+  const holdUntil = (group: Group): string | null => {
+    const floor = readInstant(text(row, `${group}_floor_until`));
+    return floor && floor.getTime() > now.getTime() ? text(row, `${group}_floor_until`) : null;
+  };
+  const named = input.groups;
+  if (named) {
+    for (const group of named) {
+      const hold = holdUntil(group);
+      if (hold) return { ok: false, status: 409, reason: "retention-hold", group, holdUntil: hold };
+    }
+  }
+  const targets = named ? [...named] : GROUPS.filter((group) => rowHasData(row, group) && !holdUntil(group));
+  if (targets.length === 0) {
+    const held = GROUPS.find((group) => rowHasData(row, group) && holdUntil(group));
+    return held
+      ? { ok: false, status: 409, reason: "retention-hold", group: held, holdUntil: holdUntil(held)! }
+      : { ok: false, status: 404, reason: "not-found" };
+  }
+  const scope = `tenant_id = ? AND stage = ? AND order_id = ? AND EXISTS (SELECT 1 FROM contact_access_audit WHERE audit_id = ?)`;
+  const scopeParams = [tenantId, stage, orderId, auditId];
   const audit = auditStatement({
-    auditId, tenantId, stage, recordKind: "order-contact", recordId: orderId, actor, action: "erase", now,
-    requireRow: { sql: rowSql, params: [tenantId, stage, orderId] },
+    auditId, tenantId, stage, recordKind: "order-contact", recordId: orderId, groups: targets, actor, action: "erase", now,
+    requireRow: { sql: `SELECT 1 FROM order_contact_vault WHERE tenant_id = ? AND stage = ? AND order_id = ?`, params: [tenantId, stage, orderId] },
   });
   const statements: QueryStatement[] = [
     batchAuditStatement(audit),
-    {
-      sql: `INSERT INTO order_contact_tombstones (tenant_id, stage, order_id, reason, at, not_after)
-            SELECT tenant_id, stage, order_id, 'erased', ?, not_after FROM order_contact_vault
-            WHERE tenant_id = ? AND stage = ? AND order_id = ?
-              AND EXISTS (SELECT 1 FROM contact_access_audit WHERE audit_id = ?)
-            ON CONFLICT (tenant_id, stage, order_id) DO UPDATE SET reason = 'erased', at = excluded.at`,
-      params: [nowIso, tenantId, stage, orderId, auditId],
-    },
-    {
-      sql: `DELETE FROM order_contact_vault WHERE tenant_id = ? AND stage = ? AND order_id = ?
-              AND EXISTS (SELECT 1 FROM contact_access_audit WHERE audit_id = ?)`,
-      params: [tenantId, stage, orderId, auditId],
-    },
+    { sql: `UPDATE order_contact_vault SET ${clearSql(targets)}, erased_at = ? WHERE ${scope}`, params: [now.toISOString(), ...scopeParams] },
+    ...normalizeStatements(scope, scopeParams),
   ];
   try {
     await requireBatch(db)(statements);
   } catch {
     return { ok: false, status: 503, reason: "audit-unavailable" };
   }
-  const audited = await db.first(`SELECT 1 AS present FROM contact_access_audit WHERE audit_id = ?`, auditId);
-  if (audited) return { ok: true };
+  if (await db.first(`SELECT 1 AS present FROM contact_access_audit WHERE audit_id = ?`, auditId)) return { ok: true, groups: targets };
   const still = await db.first(`SELECT 1 AS present FROM order_contact_vault WHERE tenant_id = ? AND stage = ? AND order_id = ?`, tenantId, stage, orderId);
   return still ? { ok: false, status: 429, reason: "quota" } : { ok: false, status: 404, reason: "not-found" };
 }
 
-/** The statement that shortens an order's contact retention when the order becomes terminal. */
-export function terminalExpiryStatement(tenantId: string, stage: VaultStage, orderId: string, terminalAt: Date): { sql: string; params: unknown[] } {
-  return {
-    sql: `UPDATE order_contact_vault SET expires_at = MIN(expires_at, ?)
-          WHERE tenant_id = ? AND stage = ? AND order_id = ? AND expires_at > ?`,
-    params: [terminalExpiryFrom(terminalAt), tenantId, stage, orderId, terminalExpiryFrom(terminalAt)],
+// ---------------------------------------------------------------------------------------------
+// Terminal transition
+// ---------------------------------------------------------------------------------------------
+
+const FAR_FUTURE = "9999-12-31T23:59:59.999Z";
+
+/** The rederived non-floor expiry of `group` for each ship-to variant the tenant's rules distinguish, as a SQL CASE. */
+function rederivedCaseSql(
+  group: Group,
+  tenantId: string,
+  stage: VaultStage,
+  placedAt: Date,
+  terminalAt: Date,
+  timeScale: number,
+  policy: RetentionPolicy,
+): string | null {
+  const tenantRules = rulesForTenant(tenantId, policy);
+  const countries = [...new Set(tenantRules.flatMap((rule) => rule.appliesWhen.shipCountries ?? []).map((c) => c.toUpperCase()))];
+  const regions = [...new Set(tenantRules.flatMap((rule) => rule.appliesWhen.regions ?? []).map((r) => r.toUpperCase()))];
+  const derive = (country: string | null, region: string | null): string | null => rederiveGroup({
+    group, ceiling: FAR_FUTURE, expiresAt: FAR_FUTURE, floorUntil: null, timeScale, stage, placedAt, terminalAt,
+    rules: rederivationRules(tenantId, country, region, policy), policy,
+  });
+  const fallback = derive(null, null);
+  if (fallback === null) return null;
+  const branches = new Map<string, string[]>();
+  const add = (condition: string, value: string | null) => {
+    if (value === null) return;
+    branches.set(value, [...(branches.get(value) ?? []), condition]);
   };
+  const countryExpr = "UPPER(TRIM(COALESCE(ship_country, '')))";
+  const regionExpr = "UPPER(TRIM(COALESCE(ship_region, '')))";
+  for (const country of countries) {
+    for (const region of regions) add(`(${countryExpr} = ${sqlLiteral(country)} AND ${regionExpr} = ${sqlLiteral(region)})`, derive(country, region));
+    add(`${countryExpr} = ${sqlLiteral(country)}`, derive(country, null));
+  }
+  for (const region of regions) add(`${regionExpr} = ${sqlLiteral(region)}`, derive(null, region));
+  const whens = [...branches.entries()]
+    .filter(([value]) => value !== fallback)
+    .map(([value, conditions]) => `WHEN ${conditions.join(" OR ")} THEN ${sqlLiteral(value)}`);
+  return whens.length === 0 ? sqlLiteral(fallback) : `CASE ${whens.join(" ")} ELSE ${sqlLiteral(fallback)} END`;
 }
 
 /**
- * The same shortening for a fulfillment transition's own batch: it applies only when the order row
- * reached a terminal state at exactly `version`, so a refused transition changes nothing.
+ * The statement for a fulfillment transition's own batch that shrinks each group's effective expiry
+ * now that the order is terminal: max(current non-floor rules given the terminal time, the row's
+ * floor_until), never above its current expiry or its ceiling. It applies only when the order row
+ * reached a terminal state at exactly `version` and the row was sealed on this stage's clock, so a
+ * refused transition changes nothing; the hourly purge re-derives anything it skips.
  */
 export function terminalTransitionExpiryStatement(
-  order: { tenantId: string; stage: VaultStage; orderId: string },
+  order: { tenantId: string; stage: VaultStage; orderId: string; placedAt: string },
   version: number,
   terminalAt: Date,
+  policy: RetentionPolicy = RETENTION_POLICY,
 ): { sql: string; params: unknown[] } {
-  const expiry = terminalExpiryFrom(terminalAt);
+  const placedAt = readInstant(order.placedAt);
+  const timeScale = order.stage === "preview" ? policy.previewTimeScale : 1;
+  const derived = placedAt && !Number.isNaN(terminalAt.getTime())
+    ? GROUPS.map((group) => [group, rederivedCaseSql(group, order.tenantId, order.stage, placedAt, terminalAt, timeScale, policy)] as const)
+    : [];
+  if (derived.length === 0 || derived.some(([, sql]) => sql === null)) {
+    return { sql: `UPDATE order_contact_vault SET time_scale = time_scale WHERE 0`, params: [] };
+  }
+  const sets = derived.map(([group, sql]) =>
+    `${group}_expires_at = CASE WHEN ${group}_expires_at IS NULL OR ${group}_ceiling IS NULL THEN ${group}_expires_at
+       ELSE MIN(${group}_expires_at, ${group}_ceiling, MAX(COALESCE(${group}_floor_until, ''), ${sql})) END`);
   return {
-    sql: `UPDATE order_contact_vault SET expires_at = ?
-      WHERE tenant_id = ? AND stage = ? AND order_id = ? AND expires_at > ?
+    sql: `UPDATE order_contact_vault SET ${sets.join(", ")}
+      WHERE tenant_id = ? AND stage = ? AND order_id = ? AND time_scale = ?
         AND EXISTS (
           SELECT 1 FROM scrappy_commerce_orders
-          WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?
+          WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ? AND placed_at IS ?
             AND fulfillment_state IN ('handed_off', 'cancelled')
         )`,
-    params: [expiry, order.tenantId, order.stage, order.orderId, expiry, order.tenantId, order.stage, order.orderId, version],
+    params: [order.tenantId, order.stage, order.orderId, timeScale, order.tenantId, order.stage, order.orderId, version, order.placedAt],
   };
 }
 
+// ---------------------------------------------------------------------------------------------
+// Purge
+// ---------------------------------------------------------------------------------------------
+
 export interface PurgeCounts {
-  purged: number;
-  tombstonesRemoved: number;
+  /** Field groups cleared, by the rule id that held them. */
+  groupsPurged: Record<string, number>;
+  /** Rows detached to unlinked facts. */
+  detached: number;
+  /** Preview rows deleted whole with their marker. */
+  previewDeleted: number;
+  /** Group expiries shrunk by re-derivation. */
   shortened: number;
 }
 
+/** SQL: the group still holds data and its effective expiry or ceiling has passed (two `now` params). */
+function expiredSql(group: Group): string {
+  return `(${hasDataSql(group)} AND (${group}_expires_at IS NULL OR ${group}_expires_at <= ? OR ${group}_ceiling <= ?))`;
+}
+
+const TERMINAL_CORRELATED_SQL = correlatedTerminalSql("v");
+
 /**
- * Purge expired order contacts. One batch tombstones and deletes every expired row (same `now`), so
- * a later resend of a purged contact meets the tombstone. Then terminal orders still holding a
- * longer expiry are shortened: to 180 days after their audited terminal time, or 180 days after
- * now when no terminal time was audited (the ledger path), never later than they already were.
+ * The hourly purge, with one clock reading: re-derive terminal orders' expiries (shrink-only), clear
+ * every group whose effective expiry has passed (its ciphertexts, its blind index, and city and full
+ * postal code for an address group), detach publication rows whose last group is gone, and delete
+ * preview rows with their marker at placed_at + the cutoff. Keyset pages, one batch each, so no
+ * page repeats. Aborts on an unreadable clock.
  */
-export async function purgeOrderContacts(db: Queryable, now: Date, limit = 500): Promise<PurgeCounts> {
-  if (Number.isNaN(now.getTime())) throw new Error("vault purge: unreadable clock");
+export async function purgeOrderContacts(
+  db: Queryable,
+  now: Date,
+  options: { pageSize?: number; shortenLimit?: number; policy?: RetentionPolicy } = {},
+): Promise<PurgeCounts> {
+  if (!(now instanceof Date) || Number.isNaN(now.getTime())) throw new Error("vault purge: unreadable clock");
+  const pageSize = Math.floor(options.pageSize ?? 50);
+  const shortenLimit = Math.floor(options.shortenLimit ?? 500);
+  if (!Number.isFinite(pageSize) || pageSize < 1 || pageSize > 90) throw new Error("vault purge: unreadable page size");
+  if (!Number.isFinite(shortenLimit) || shortenLimit < 0) throw new Error("vault purge: unreadable limit");
+  const policy = options.policy ?? RETENTION_POLICY;
+  const batch = requireBatch(db);
   const nowIso = now.toISOString();
-  const before = await db.first<{ n: number }>(
-    `SELECT COUNT(*) AS n FROM order_contact_vault WHERE expires_at <= ? OR not_after <= ?`, nowIso, nowIso,
-  );
-  const tombsBefore = await db.first<{ n: number }>(`SELECT COUNT(*) AS n FROM order_contact_tombstones WHERE not_after <= ?`, nowIso);
-  await requireBatch(db)([
-    {
-      sql: `INSERT INTO order_contact_tombstones (tenant_id, stage, order_id, reason, at, not_after)
-            SELECT tenant_id, stage, order_id, 'purged', ?, not_after FROM order_contact_vault
-            WHERE expires_at <= ? OR not_after <= ?
-            ON CONFLICT (tenant_id, stage, order_id) DO NOTHING`,
-      params: [nowIso, nowIso, nowIso],
-    },
-    { sql: `DELETE FROM order_contact_vault WHERE expires_at <= ? OR not_after <= ?`, params: [nowIso, nowIso] },
-    { sql: `DELETE FROM order_contact_tombstones WHERE not_after <= ?`, params: [nowIso] },
-  ]);
-  const terminal = await db.all<{ tenant_id: string; stage: VaultStage; order_id: string; expires_at: string; at: string | null }>(
-    `SELECT v.tenant_id, v.stage, v.order_id, v.expires_at,
-            (SELECT MIN(a.at) FROM scrappy_shipment_audit a
-              WHERE a.tenant_id = v.tenant_id AND a.stage = v.stage AND a.order_id = v.order_id
-                AND ((a.kind = 'transition' AND a.to_state = 'handed_off') OR (a.kind = 'pending-cancel' AND a.to_state = 'confirmed'))) AS at
+  const counts: PurgeCounts = { groupsPurged: {}, detached: 0, previewDeleted: 0, shortened: 0 };
+
+  // 1. Shrink-only re-derivation for terminal orders, before clearing, so this run clears what it shrank.
+  let cursor = "";
+  while (counts.shortened < shortenLimit) {
+    const rows = await db.all<VaultRow>(
+      `SELECT v.*, o.placed_at AS order_placed_at, o.fulfillment_state AS order_fulfillment_state, (${TERMINAL_CORRELATED_SQL}) AS order_terminal_at
+       FROM order_contact_vault v
+       JOIN scrappy_commerce_orders o ON o.tenant_id = v.tenant_id AND o.stage = v.stage AND o.order_id = v.order_id
+       WHERE o.fulfillment_state IN ('handed_off', 'cancelled') AND v.fact_id > ?
+       ORDER BY v.fact_id LIMIT ?`,
+      cursor, pageSize,
+    );
+    if (rows.length === 0) break;
+    const updates: QueryStatement[] = [];
+    for (const row of rows) {
+      cursor = String(row.fact_id);
+      const times = orderTimes(row.order_placed_at, row.order_fulfillment_state, row.order_terminal_at);
+      if (times === "order-time-unreadable") continue;
+      const effective = effectiveExpiries(row, String(row.tenant_id), row.stage as VaultStage, times, policy);
+      for (const group of GROUPS) {
+        const current = text(row, `${group}_expires_at`);
+        const next = effective[group];
+        if (!rowHasData(row, group) || !current || !next || next >= current) continue;
+        if (counts.shortened + updates.length >= shortenLimit) break;
+        updates.push({
+          sql: `UPDATE order_contact_vault SET ${group}_expires_at = ? WHERE fact_id = ? AND ${group}_expires_at = ?`,
+          params: [next, row.fact_id, current],
+        });
+      }
+    }
+    if (updates.length > 0) await batch(updates);
+    counts.shortened += updates.length;
+    if (rows.length < pageSize) break;
+  }
+
+  // 2. Clear expired groups and detach, page by page.
+  cursor = "";
+  for (;;) {
+    const rows = await db.all<VaultRow>(
+      `SELECT fact_id, stage, ${GROUPS.map((group) => `${group}_rule, ${group}_expires_at, ${group}_ceiling, ${hasDataSql(group)} AS ${group}_has`).join(", ")}
+       FROM order_contact_vault
+       WHERE fact_id > ? AND (${GROUPS.map(expiredSql).join(" OR ")})
+       ORDER BY fact_id LIMIT ?`,
+      cursor, ...GROUPS.flatMap(() => [nowIso, nowIso]), pageSize,
+    );
+    if (rows.length === 0) break;
+    const ids = rows.map((row) => String(row.fact_id));
+    const inList = ids.map(() => "?").join(", ");
+    const statements: QueryStatement[] = GROUPS.map((group) => ({
+      sql: `UPDATE order_contact_vault SET ${clearSql([group])} WHERE fact_id IN (${inList}) AND ${expiredSql(group)}`,
+      params: [...ids, nowIso, nowIso],
+    }));
+    statements.push(...normalizeStatements(`fact_id IN (${inList})`, ids));
+    await batch(statements);
+    for (const row of rows) {
+      let remaining = 0;
+      for (const group of GROUPS) {
+        if (Number(row[`${group}_has`]) !== 1) continue;
+        const expires = text(row, `${group}_expires_at`);
+        const ceiling = text(row, `${group}_ceiling`);
+        const due = expires === null || expires <= nowIso || (ceiling !== null && ceiling <= nowIso);
+        if (!due) {
+          remaining += 1;
+          continue;
+        }
+        const rule = text(row, `${group}_rule`) ?? "unrecorded";
+        counts.groupsPurged[rule] = (counts.groupsPurged[rule] ?? 0) + 1;
+      }
+      if (remaining === 0 && row.stage === "publication") counts.detached += 1;
+    }
+    cursor = ids[ids.length - 1]!;
+    if (rows.length < pageSize) break;
+  }
+
+  // 3. Preview: delete the whole row and its marker at placed_at + the cutoff.
+  let markerCursor: [string, string] = ["", ""];
+  for (;;) {
+    const markers = await db.all<{ tenant_id: string; order_id: string; placed_at: unknown }>(
+      `SELECT m.tenant_id, m.order_id, o.placed_at FROM order_contact_markers m
+       JOIN scrappy_commerce_orders o ON o.tenant_id = m.tenant_id AND o.stage = m.stage AND o.order_id = m.order_id
+       WHERE m.stage = 'preview' AND (m.tenant_id, m.order_id) > (?, ?)
+       ORDER BY m.tenant_id, m.order_id LIMIT ?`,
+      ...markerCursor, pageSize,
+    );
+    if (markers.length === 0) break;
+    const due = markers.filter((marker) => {
+      const placed = readInstant(marker.placed_at);
+      return placed !== null && nowIso >= previewDeleteAt(placed, policy);
+    });
+    if (due.length > 0) {
+      const pairs = due.map(() => "(tenant_id = ? AND order_id = ?)").join(" OR ");
+      const params = due.flatMap((marker) => [marker.tenant_id, marker.order_id]);
+      await batch([
+        { sql: `DELETE FROM order_contact_vault WHERE stage = 'preview' AND (${pairs})`, params },
+        { sql: `DELETE FROM order_contact_markers WHERE stage = 'preview' AND (${pairs})`, params },
+      ]);
+      counts.previewDeleted += due.length;
+    }
+    const last = markers[markers.length - 1]!;
+    markerCursor = [last.tenant_id, last.order_id];
+    if (markers.length < pageSize) break;
+  }
+  return counts;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Rotation
+// ---------------------------------------------------------------------------------------------
+
+/** Correlated reference checks for every data-key purpose (orders and messages). */
+export const DATA_KEY_REFERENCES: Readonly<Record<DataKeyPurpose, string>> = {
+  "order-contact": `SELECT 1 FROM order_contact_vault v WHERE v.tenant_id = contact_vault_data_keys.tenant_id
+    AND v.stage = contact_vault_data_keys.stage AND v.order_kid = contact_vault_data_keys.kid`,
+  "contact-message": `SELECT 1 FROM contact_messages m WHERE m.tenant_id = contact_vault_data_keys.tenant_id
+    AND m.stage = contact_vault_data_keys.stage AND m.msg_kid = contact_vault_data_keys.kid`,
+  "blind-index": `SELECT 1 FROM order_contact_vault v WHERE v.tenant_id = contact_vault_data_keys.tenant_id
+    AND v.stage = contact_vault_data_keys.stage AND v.bidx_kid = contact_vault_data_keys.kid
+    UNION ALL SELECT 1 FROM contact_messages m WHERE m.tenant_id = contact_vault_data_keys.tenant_id
+    AND m.stage = contact_vault_data_keys.stage AND m.bidx_kid = contact_vault_data_keys.kid`,
+};
+
+/** Rows per table whose blind indexes one rotation run recomputes; the next run takes the rest. */
+export const BLIND_INDEX_RECOMPUTE_LIMIT = 200;
+
+/**
+ * One table's blind-index recompute step: re-index up to `limit` still-sealed rows whose bidx_kid is
+ * retired under the active blind-index key, returning how many rows it moved. contactMessages.ts
+ * supplies the messages step; the sweep passes it in, since orders never import engagement.
+ */
+export type BlindIndexRecompute = (db: Queryable, kms: KmsClient, now: Date, limit: number) => Promise<number>;
+
+/**
+ * Recompute order rows indexed under a retired blind-index kid: decrypt the email and phone fields
+ * under the row's order key, HMAC the normalized values with the active blind-index key, and write
+ * both indexes and bidx_kid in ONE update conditioned on the row being unchanged since it was read.
+ * An index whose field no longer opens is cleared. Throws VaultKeyUnavailableError when KMS refuses.
+ */
+export const recomputeOrderBlindIndexes: BlindIndexRecompute = async (db, kms, now, limit) => {
+  const rows = await db.all<VaultRow>(
+    `SELECT v.fact_id, v.tenant_id, v.stage, v.order_kid, v.bidx_kid, v.email_ct, v.email_bidx, v.email_ceiling,
+            v.phone_ct, v.phone_bidx, v.phone_ceiling
      FROM order_contact_vault v
-     JOIN scrappy_commerce_orders o ON o.tenant_id = v.tenant_id AND o.stage = v.stage AND o.order_id = v.order_id
-     WHERE o.fulfillment_state IN ('handed_off', 'cancelled')
-     LIMIT ?`,
-    limit,
+     JOIN contact_vault_data_keys k ON k.tenant_id = v.tenant_id AND k.stage = v.stage AND k.purpose = ? AND k.kid = v.bidx_kid
+     WHERE k.retired_at IS NOT NULL
+     ORDER BY v.fact_id LIMIT ?`,
+    BIDX_KEY, Math.max(0, Math.floor(limit)),
   );
-  const updates: QueryStatement[] = [];
-  for (const row of terminal) {
-    const at = readInstant(row.at) ?? now;
-    const statement = terminalExpiryStatement(row.tenant_id, row.stage, row.order_id, at);
-    if (terminalExpiryFrom(at) < row.expires_at) updates.push(statement);
+  let moved = 0;
+  for (const row of rows) {
+    const tenantId = String(row.tenant_id);
+    const stage = row.stage as VaultStage;
+    const factId = String(row.fact_id);
+    const active = await activeKey(db, kms, keyContext(tenantId, stage, BIDX_KEY), now);
+    // Rotation installs the new active key before this runs; never mint one from here.
+    if (active.pending.length > 0 || active.kid === row.bidx_kid) continue;
+    const orderKid = text(row, "order_kid");
+    const orderKey = orderKid ? await keyForKid(db, kms, keyContext(tenantId, stage, ORDER_KEY), orderKid) : null;
+    const reindex = async (group: "email" | "phone"): Promise<string | null> => {
+      const sealed = text(row, `${group}_ct`);
+      const ceiling = text(row, `${group}_ceiling`);
+      if (text(row, `${group}_bidx`) === null || sealed === null || ceiling === null || !orderKey || !orderKid) return null;
+      const value = await openField(orderKey, fieldBinding(tenantId, stage, factId, orderKid, `${group}_ct`, ceiling), sealed);
+      const normalized = value === null ? null : group === "email" ? normalizeEmail(value) : normalizePhone(value);
+      return normalized === null ? null : blindIndex(active.key, normalized);
+    };
+    const email = await reindex("email");
+    const phone = await reindex("phone");
+    const updated = await db.all(
+      `UPDATE order_contact_vault SET email_bidx = ?, phone_bidx = ?, bidx_kid = ?
+       WHERE fact_id = ? AND bidx_kid IS ? AND email_bidx IS ? AND phone_bidx IS ? AND email_ct IS ? AND phone_ct IS ?
+         AND EXISTS (SELECT 1 FROM contact_vault_data_keys WHERE tenant_id = ? AND stage = ? AND purpose = ? AND kid = ? AND retired_at IS NULL)
+       RETURNING fact_id`,
+      email, phone, email === null && phone === null ? null : active.kid,
+      factId, row.bidx_kid, row.email_bidx, row.phone_bidx, row.email_ct, row.phone_ct,
+      tenantId, stage, BIDX_KEY, active.kid,
+    );
+    moved += updated.length;
   }
-  if (updates.length > 0) await requireBatch(db)(updates);
-  return {
-    purged: Number(before?.n ?? 0),
-    tombstonesRemoved: Number(tombsBefore?.n ?? 0),
-    shortened: updates.length,
-  };
+  return moved;
+};
+
+/**
+ * Rotate data keys older than 365 days, recompute blind indexes still under a retired blind-index
+ * kid (orders here, plus each step in `recompute`, bounded per run), then delete retired keys no row
+ * references any more.
+ */
+export async function rotateContactVaultKeys(
+  db: Queryable,
+  kms: KmsClient,
+  now: Date,
+  options: { recompute?: readonly BlindIndexRecompute[]; recomputeLimit?: number } = {},
+): Promise<{ rotated: number; recomputed: number }> {
+  if (!(now instanceof Date) || Number.isNaN(now.getTime())) throw new Error("vault rotation: unreadable clock");
+  const { rotated } = await rotateDueKeys(db, kms, now);
+  const limit = options.recomputeLimit ?? BLIND_INDEX_RECOMPUTE_LIMIT;
+  let recomputed = 0;
+  for (const step of [recomputeOrderBlindIndexes, ...(options.recompute ?? [])]) recomputed += await step(db, kms, now, limit);
+  await deleteUnreferencedRetiredKeys(db, DATA_KEY_REFERENCES);
+  return { rotated, recomputed };
 }