@tokenoftrust/storefront-runner 4.10.1 → 4.11.1

package/apps/storefront/src/lib/customers/contactVault/retention.ts

@@ -1,11 +1,35 @@
 /**
- * Contact vault retention. `notAfter` is the hard ceiling bound into the AAD: 365 days after the
- * order was placed (or the message was received). Once an order is terminal (handed off or
- * cancelled) its contact expires 180 days after that, never later than `notAfter`.
+ * Contact vault retention arithmetic over the declared rule table (retentionPolicy.ts).
+ *
+ * Every sealed order carries, per field group:
+ * - `ceiling`: the latest instant any applicable rule could require (the terminal-relative
+ *   fulfillment rule counted at its cap). Immutable while the group is sealed; bound into the AAD.
+ * - `expiresAt`: the effective expiry. Starts at the value derived from the current terminal time
+ *   and only ever shrinks, never above the ceiling and never below `floorUntil`.
+ * - `floorUntil`: the latest end of the floor rules that applied at seal, or null. Immutable.
+ * - `rule`: the id of the rule that set the seal-time expiry.
+ *
+ * Preview rows run the same rules on a compressed clock: every rule's offset is divided by the
+ * policy's `previewTimeScale` (rounded down), and every preview ceiling is clamped to the anchor
+ * plus `previewCutoffDays`, past which nothing is admitted. The anchor is placed_at for orders and
+ * received_at for messages. A terminal-relative rule measures from the observed terminal instant,
+ * which on preview already lies on the compressed clock, so only its duration and cap are scaled.
+ *
+ * All functions are pure; `now` is always passed in.
  */
 
-export const CONTACT_RETENTION_DAYS = 365;
-export const TERMINAL_RETENTION_DAYS = 180;
+import {
+  GROUPS,
+  RETENTION_POLICY,
+  applicableRules,
+  ruleVersion,
+  type Group,
+  type RetentionPolicy,
+  type Rule,
+} from "./retentionPolicy.js";
+
+export type RetentionStage = "preview" | "publication";
+
 const DAY_MS = 86_400_000;
 
 const ISO_INSTANT = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:?\d{2})$/;
@@ -22,23 +46,257 @@ export function readInstant(value: unknown): Date | null {
   return Number.isNaN(parsed.getTime()) ? null : parsed;
 }
 
+const STAMP_SUFFIX = /#\d{6,}$/;
+
+/**
+ * A shipment-audit stamp (`<ISO>#NNNNNN`, the sequence suffix written by the fulfillment service)
+ * or a bare ISO instant, read strictly; null otherwise.
+ */
+export function readStampInstant(value: unknown): Date | null {
+  if (typeof value !== "string") return null;
+  return readInstant(value.replace(STAMP_SUFFIX, ""));
+}
+
+/**
+ * The order's terminal time (handed off, or a confirmed pending-cancel): the earliest matching
+ * shipment-audit stamp with its `#NNNNNN` suffix removed. Bind tenant_id, stage, order_id; read
+ * the `at` column with `readStampInstant`.
+ */
+export const TERMINAL_AT_SQL = `SELECT MIN(substr(at, 1, instr(at || '#', '#') - 1)) 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'))`;
+
+export interface GroupRetention {
+  ceiling: string;
+  expiresAt: string;
+  floorUntil: string | null;
+  rule: string;
+}
+
+export type SealRetentionResult =
+  | { kind: "refused"; reason: "contact-expired" | "order-time-unreadable" }
+  | { kind: "ok"; timeScale: number; ruleVersion: string; groups: Record<Group, GroupRetention> };
+
+export interface SealRetentionInput {
+  stage: RetentionStage;
+  placedAt: Date;
+  terminalAt: Date | null;
+  shipCountry: string | null;
+  shipRegion: string | null;
+  regulated: boolean;
+  tenantId: string;
+  now: Date;
+  policy?: RetentionPolicy;
+}
+
+function validDate(value: unknown): value is Date {
+  return value instanceof Date && !Number.isNaN(value.getTime());
+}
+
+function timeScaleFor(stage: RetentionStage, policy: RetentionPolicy): number {
+  return stage === "preview" ? policy.previewTimeScale : 1;
+}
+
+function scaled(ms: number, scale: number): number {
+  return Math.floor(ms / scale);
+}
+
+function previewCutoffMs(anchorMs: number, policy: RetentionPolicy): number {
+  return anchorMs + policy.previewCutoffDays * DAY_MS;
+}
+
+/** End of a rule (ms) given the terminal time; `terminalMs` null means not yet terminal. */
+function ruleEnd(rule: Rule, placedMs: number, terminalMs: number | null, scale: number): number {
+  const d = rule.duration;
+  switch (d.kind) {
+    case "days-from-placed":
+      return placedMs + scaled(d.days * DAY_MS, scale);
+    case "days-after-terminal": {
+      const cap = placedMs + scaled(d.capDaysFromPlaced * DAY_MS, scale);
+      if (terminalMs === null) return cap;
+      return Math.min(terminalMs + scaled(d.days * DAY_MS, scale), cap);
+    }
+    case "through-nth-full-calendar-year-after-placed": {
+      const end = Date.UTC(new Date(placedMs).getUTCFullYear() + d.n + 1, 0, 1);
+      return placedMs + scaled(end - placedMs, scale);
+    }
+  }
+}
+
+/** The latest end a rule could ever require: a terminal-relative rule counts at its cap. */
+function ruleCeiling(rule: Rule, placedMs: number, scale: number): number {
+  return ruleEnd(rule, placedMs, null, scale);
+}
+
+function fulfillmentRule(policy: RetentionPolicy): Rule {
+  const rule = policy.rules.find((r) => r.groups.length === GROUPS.length && r.duration.kind === "days-after-terminal");
+  if (!rule) throw new Error("retention policy has no terminal-relative rule covering every group");
+  return rule;
+}
+
+function rulesForGroup(group: Group, rules: readonly Rule[], policy: RetentionPolicy): Rule[] {
+  const covering = rules.filter((rule) => rule.groups.includes(group));
+  return covering.length > 0 ? covering : [fulfillmentRule(policy)];
+}
+
+function iso(ms: number): string {
+  return new Date(ms).toISOString();
+}
+
+/**
+ * Seal-time retention for every group of an order. Refuses when the inputs are not real instants,
+ * when a preview order is at or past its cutoff, or when every group's expiry has already passed.
+ */
+export async function sealRetention(input: SealRetentionInput): Promise<SealRetentionResult> {
+  const policy = input.policy ?? RETENTION_POLICY;
+  if (!validDate(input.placedAt) || !validDate(input.now) || (input.terminalAt !== null && !validDate(input.terminalAt))) {
+    return { kind: "refused", reason: "order-time-unreadable" };
+  }
+  const nowMs = input.now.getTime();
+  const placedMs = input.placedAt.getTime();
+  const terminalMs = input.terminalAt ? input.terminalAt.getTime() : null;
+  const scale = timeScaleFor(input.stage, policy);
+  const cutoff = input.stage === "preview" ? previewCutoffMs(placedMs, policy) : Infinity;
+  if (nowMs >= cutoff) return { kind: "refused", reason: "contact-expired" };
+
+  const rules = applicableRules(
+    input.tenantId,
+    { shipCountry: input.shipCountry, shipRegion: input.shipRegion, regulated: input.regulated },
+    policy,
+  );
+  const groups = {} as Record<Group, GroupRetention>;
+  let anyLive = false;
+  for (const group of GROUPS) {
+    const covering = rulesForGroup(group, rules, policy);
+    const ceiling = Math.min(cutoff, Math.max(...covering.map((rule) => ruleCeiling(rule, placedMs, scale))));
+    const ends = covering.map((rule) => ({ rule, end: ruleEnd(rule, placedMs, terminalMs, scale) }));
+    const latest = Math.max(...ends.map((entry) => entry.end));
+    const binding = ends.find((entry) => entry.end === latest && entry.rule.floor) ?? ends.find((entry) => entry.end === latest)!;
+    const expiresAt = Math.min(latest, ceiling);
+    const floors = ends.filter((entry) => entry.rule.floor).map((entry) => entry.end);
+    const floorUntil = floors.length > 0 ? Math.min(Math.max(...floors), ceiling) : null;
+    if (expiresAt > nowMs) anyLive = true;
+    groups[group] = {
+      ceiling: iso(ceiling),
+      expiresAt: iso(expiresAt),
+      floorUntil: floorUntil === null ? null : iso(floorUntil),
+      rule: binding.rule.id,
+    };
+  }
+  if (!anyLive) return { kind: "refused", reason: "contact-expired" };
+  return { kind: "ok", timeScale: scale, ruleVersion: await ruleVersion(policy), groups };
+}
+
+export interface RederiveGroupInput {
+  group: Group;
+  ceiling: string;
+  expiresAt: string;
+  floorUntil: string | null;
+  /** The time scale recorded on the row at seal. */
+  timeScale: number;
+  stage: RetentionStage;
+  placedAt: Date;
+  terminalAt: Date | null;
+  /** The rules from the current table that apply to this order (`applicableRules`). */
+  rules: readonly Rule[];
+  policy?: RetentionPolicy;
+}
+
+/**
+ * The group's new effective expiry under the current table and terminal time: the latest current
+ * non-floor rule, raised to the recorded floor, and never above the ceiling or the current expiry.
+ * Null when a recorded value is unreadable, so the caller leaves the row unchanged.
+ */
+export function rederiveGroup(input: RederiveGroupInput): string | null {
+  const policy = input.policy ?? RETENTION_POLICY;
+  const ceiling = readInstant(input.ceiling);
+  const current = readInstant(input.expiresAt);
+  const floor = input.floorUntil === null ? null : readInstant(input.floorUntil);
+  if (!ceiling || !current || (input.floorUntil !== null && !floor)) return null;
+  if (!validDate(input.placedAt) || (input.terminalAt !== null && !validDate(input.terminalAt))) return null;
+  if (!Number.isInteger(input.timeScale) || input.timeScale < 1) return null;
+  const placedMs = input.placedAt.getTime();
+  const terminalMs = input.terminalAt ? input.terminalAt.getTime() : null;
+  const nonFloor = input.rules.filter((rule) => !rule.floor && rule.groups.includes(input.group));
+  const covering = nonFloor.length > 0 ? nonFloor : [fulfillmentRule(policy)];
+  let next = Math.max(...covering.map((rule) => ruleEnd(rule, placedMs, terminalMs, input.timeScale)));
+  if (floor) next = Math.max(next, floor.getTime());
+  next = Math.min(next, ceiling.getTime(), current.getTime());
+  if (input.stage === "preview") next = Math.min(next, previewCutoffMs(placedMs, policy));
+  return iso(next);
+}
+
+export type MessageRetentionResult =
+  | { kind: "refused"; reason: "contact-expired" | "message-time-unreadable" }
+  | {
+      kind: "ok";
+      timeScale: number;
+      ruleVersion: string;
+      rule: string;
+      ceiling: string;
+      expiresAt: string;
+      /** Preview only: when the whole row is deleted. */
+      deleteAt: string | null;
+    };
+
+export async function messageRetention(input: {
+  stage: RetentionStage;
+  receivedAt: Date;
+  now: Date;
+  policy?: RetentionPolicy;
+}): Promise<MessageRetentionResult> {
+  const policy = input.policy ?? RETENTION_POLICY;
+  if (!validDate(input.receivedAt) || !validDate(input.now)) return { kind: "refused", reason: "message-time-unreadable" };
+  const receivedMs = input.receivedAt.getTime();
+  const scale = timeScaleFor(input.stage, policy);
+  const deleteAt = input.stage === "preview" ? previewCutoffMs(receivedMs, policy) : null;
+  const ceiling = Math.min(receivedMs + scaled(policy.message.daysFromReceived * DAY_MS, scale), deleteAt ?? Infinity);
+  const nowMs = input.now.getTime();
+  if (nowMs >= ceiling || (deleteAt !== null && nowMs >= deleteAt)) return { kind: "refused", reason: "contact-expired" };
+  return {
+    kind: "ok",
+    timeScale: scale,
+    ruleVersion: await ruleVersion(policy),
+    rule: policy.message.id,
+    ceiling: iso(ceiling),
+    expiresAt: iso(ceiling),
+    deleteAt: deleteAt === null ? null : iso(deleteAt),
+  };
+}
+
+/** True while a group may be read: strictly before both its expiry and its ceiling. */
+export function isGroupReadable(now: Date, expiresAt: string | null, ceiling: string | null): boolean {
+  if (!validDate(now)) return false;
+  const expires = readInstant(expiresAt);
+  const cap = readInstant(ceiling);
+  if (!expires || !cap) return false;
+  const nowMs = now.getTime();
+  return nowMs < expires.getTime() && nowMs < cap.getTime();
+}
+
+/** When a preview order's row, facts and marker are deleted whole. */
+export function previewDeleteAt(placedAt: Date, policy: RetentionPolicy = RETENTION_POLICY): string {
+  return iso(previewCutoffMs(placedAt.getTime(), policy));
+}
+
+const LEGACY_CONTACT_RETENTION_DAYS = 365;
+const LEGACY_TERMINAL_RETENTION_DAYS = 180;
+
 export function notAfterFrom(start: Date): string {
-  return new Date(start.getTime() + CONTACT_RETENTION_DAYS * DAY_MS).toISOString();
+  return iso(start.getTime() + LEGACY_CONTACT_RETENTION_DAYS * DAY_MS);
 }
 
-/** The expiry for a record whose ceiling is `notAfter`, given the order's terminal time if any. */
 export function expiresAtFor(notAfter: string, terminalAt: Date | null): string {
   if (!terminalAt) return notAfter;
-  const terminal = new Date(terminalAt.getTime() + TERMINAL_RETENTION_DAYS * DAY_MS).toISOString();
+  const terminal = terminalExpiryFrom(terminalAt);
   return terminal < notAfter ? terminal : notAfter;
 }
 
-/** True while a record may still be read: strictly before both its expiry and its ceiling. */
 export function isReadable(now: Date, expiresAt: string, notAfter: string): boolean {
-  const iso = now.toISOString();
-  return iso < expiresAt && iso < notAfter;
+  const at = now.toISOString();
+  return at < expiresAt && at < notAfter;
 }
 
 export function terminalExpiryFrom(at: Date): string {
-  return new Date(at.getTime() + TERMINAL_RETENTION_DAYS * DAY_MS).toISOString();
+  return iso(at.getTime() + LEGACY_TERMINAL_RETENTION_DAYS * DAY_MS);
 }

package/apps/storefront/src/lib/customers/contactVault/retentionPolicy.ts

@@ -0,0 +1,290 @@
+/**
+ * The declared, reviewed retention rule table for the contact vault.
+ *
+ * Each field group of a sealed order keeps its contact data for as long as the longest rule that
+ * applies to it (retention.ts does the arithmetic). A rule names its authority: a statute citation,
+ * or 'owner policy' where no statute is cited. Rules marked `floor` record a seal-time
+ * `floor_until` that no later rule change, override or tenant-class change can shorten.
+ *
+ * Owner policy rules are pending counsel review. No rule here claims a GDPR Article 17(3)
+ * exemption from a US statute.
+ *
+ * Per-tenant overrides may add a rule (new id) or lengthen a default (same id). `validatePolicy`
+ * refuses an override that shortens, narrows or un-floors a default rule.
+ */
+
+export const GROUPS = ["identity", "email", "phone", "ship", "bill"] as const;
+export type Group = (typeof GROUPS)[number];
+
+export type RuleDuration =
+  | { kind: "days-from-placed"; days: number }
+  | { kind: "days-after-terminal"; days: number; capDaysFromPlaced: number }
+  | { kind: "through-nth-full-calendar-year-after-placed"; n: number };
+
+export interface RuleAppliesWhen {
+  /** ISO 3166-1 alpha-2 ship-to countries. Absent means any ship-to country. */
+  shipCountries?: readonly string[];
+  /** Ship-to regions (subdivision codes). Absent means any region. */
+  regions?: readonly string[];
+  /** Present means the rule applies only to orders of a regulated tenant. */
+  regulated?: true;
+}
+
+export interface Rule {
+  id: string;
+  purpose: string;
+  authority: string;
+  groups: readonly Group[];
+  duration: RuleDuration;
+  appliesWhen: RuleAppliesWhen;
+  floor: boolean;
+}
+
+export interface MessageRule {
+  id: string;
+  purpose: string;
+  authority: string;
+  daysFromReceived: number;
+}
+
+export interface RetentionPolicy {
+  rules: readonly Rule[];
+  tenantOverrides: Readonly<Record<string, readonly Rule[]>>;
+  message: MessageRule;
+  previewTimeScale: number;
+  previewCutoffDays: number;
+}
+
+const OWNER_POLICY = "owner policy";
+
+/** EU member states, the EEA additions (IS, LI, NO) and the United Kingdom (GB). */
+export const EU_EEA_UK: readonly string[] = [
+  "AT", "BE", "BG", "HR", "CY", "CZ", "DK", "EE", "FI", "FR", "DE", "GR", "HU", "IE", "IT", "LV",
+  "LT", "LU", "MT", "NL", "PL", "PT", "RO", "SK", "SI", "ES", "SE",
+  "IS", "LI", "NO",
+  "GB",
+];
+
+export const DEFAULT_RULES: readonly Rule[] = [
+  {
+    id: "fulfillment-and-service",
+    purpose: "Fulfil the order and answer service requests about it",
+    authority: OWNER_POLICY,
+    groups: GROUPS,
+    duration: { kind: "days-after-terminal", days: 90, capDaysFromPlaced: 730 },
+    appliesWhen: {},
+    floor: false,
+  },
+  {
+    id: "card-disputes",
+    purpose: "Answer card chargebacks and payment disputes",
+    authority: OWNER_POLICY,
+    groups: ["identity", "email", "phone", "ship", "bill"],
+    duration: { kind: "days-from-placed", days: 540 },
+    appliesWhen: {},
+    floor: false,
+  },
+  {
+    id: "returns-and-warranty",
+    purpose: "Handle returns and warranty claims",
+    authority: OWNER_POLICY,
+    groups: ["identity", "email", "ship"],
+    duration: { kind: "days-from-placed", days: 365 },
+    appliesWhen: {},
+    floor: false,
+  },
+  {
+    id: "returns-and-warranty-eu-eea-uk",
+    purpose: "Handle returns and legal-guarantee claims for EU, EEA and UK ship-to addresses",
+    authority: OWNER_POLICY,
+    groups: ["identity", "email", "ship"],
+    duration: { kind: "days-from-placed", days: 730 },
+    appliesWhen: { shipCountries: EU_EEA_UK },
+    floor: false,
+  },
+  {
+    id: "sales-tax-sourcing",
+    purpose: "Substantiate destination sourcing of sales tax",
+    authority: OWNER_POLICY,
+    groups: ["ship"],
+    duration: { kind: "through-nth-full-calendar-year-after-placed", n: 4 },
+    appliesWhen: { shipCountries: ["US"] },
+    floor: false,
+  },
+  {
+    id: "legal-claims",
+    purpose: "Establish, exercise or defend legal claims about the sale",
+    authority: OWNER_POLICY,
+    groups: ["identity", "ship"],
+    duration: { kind: "through-nth-full-calendar-year-after-placed", n: 3 },
+    appliesWhen: {},
+    floor: false,
+  },
+  {
+    id: "pact-delivery-sale",
+    purpose: "Keep delivery-sale records of covered products",
+    authority:
+      "15 U.S.C. 376a(c) for delivery sales of covered products; applying it to every order of a regulated tenant is owner policy",
+    groups: ["identity", "ship"],
+    duration: { kind: "through-nth-full-calendar-year-after-placed", n: 4 },
+    appliesWhen: { shipCountries: ["US"], regulated: true },
+    floor: true,
+  },
+];
+
+export const TENANT_OVERRIDES: Readonly<Record<string, readonly Rule[]>> = {};
+
+export const MESSAGE_RULE: MessageRule = {
+  id: "contact-message",
+  purpose: "Answer a storefront contact message",
+  authority: OWNER_POLICY,
+  daysFromReceived: 365,
+};
+
+export const RETENTION_POLICY: RetentionPolicy = {
+  rules: DEFAULT_RULES,
+  tenantOverrides: TENANT_OVERRIDES,
+  message: MESSAGE_RULE,
+  previewTimeScale: 6261,
+  previewCutoffDays: 7,
+};
+
+/** The rules for one tenant: defaults with that tenant's overrides replacing by id or appended. */
+export function rulesForTenant(tenantId: string, policy: RetentionPolicy = RETENTION_POLICY): Rule[] {
+  const overrides = Object.prototype.hasOwnProperty.call(policy.tenantOverrides, tenantId) ? policy.tenantOverrides[tenantId]! : [];
+  const byId = new Map(overrides.map((rule) => [rule.id, rule]));
+  const merged = policy.rules.map((rule) => byId.get(rule.id) ?? rule);
+  const defaultIds = new Set(policy.rules.map((rule) => rule.id));
+  for (const rule of overrides) if (!defaultIds.has(rule.id)) merged.push(rule);
+  return merged;
+}
+
+export interface OrderFacts {
+  shipCountry: string | null;
+  shipRegion: string | null;
+  regulated: boolean;
+}
+
+function normalizeCode(value: string | null): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim().toUpperCase();
+  return trimmed === "" ? null : trimmed;
+}
+
+export function ruleApplies(rule: Rule, facts: OrderFacts): boolean {
+  const when = rule.appliesWhen;
+  if (when.regulated && facts.regulated !== true) return false;
+  if (when.shipCountries) {
+    const country = normalizeCode(facts.shipCountry);
+    if (country === null || !when.shipCountries.includes(country)) return false;
+  }
+  if (when.regions) {
+    const region = normalizeCode(facts.shipRegion);
+    if (region === null || !when.regions.map((r) => r.toUpperCase()).includes(region)) return false;
+  }
+  return true;
+}
+
+/** The tenant's rules that apply to an order with these facts. */
+export function applicableRules(tenantId: string, facts: OrderFacts, policy: RetentionPolicy = RETENTION_POLICY): Rule[] {
+  return rulesForTenant(tenantId, policy).filter((rule) => ruleApplies(rule, facts));
+}
+
+function isPositiveInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+
+function validateRuleShape(rule: Rule, where: string): void {
+  if (typeof rule.id !== "string" || rule.id.trim() === "") throw new Error(`${where}: rule id is required`);
+  if (typeof rule.authority !== "string" || rule.authority.trim() === "") throw new Error(`${where}: rule ${rule.id} names no authority`);
+  if (!Array.isArray(rule.groups) || rule.groups.length === 0 || rule.groups.some((g) => !(GROUPS as readonly string[]).includes(g))) {
+    throw new Error(`${where}: rule ${rule.id} has invalid groups`);
+  }
+  const d = rule.duration;
+  const ok =
+    (d.kind === "days-from-placed" && isPositiveInteger(d.days)) ||
+    (d.kind === "days-after-terminal" && isPositiveInteger(d.days) && isPositiveInteger(d.capDaysFromPlaced)) ||
+    (d.kind === "through-nth-full-calendar-year-after-placed" && isPositiveInteger(d.n));
+  if (!ok) throw new Error(`${where}: rule ${rule.id} has an invalid duration`);
+}
+
+function durationNotShorter(next: RuleDuration, base: RuleDuration): boolean {
+  if (next.kind === "days-from-placed" && base.kind === "days-from-placed") return next.days >= base.days;
+  if (next.kind === "days-after-terminal" && base.kind === "days-after-terminal") {
+    return next.days >= base.days && next.capDaysFromPlaced >= base.capDaysFromPlaced;
+  }
+  if (next.kind === "through-nth-full-calendar-year-after-placed" && base.kind === "through-nth-full-calendar-year-after-placed") {
+    return next.n >= base.n;
+  }
+  return false;
+}
+
+/** True when `next` applies to every order `base` applies to. */
+function appliesAtLeastAsWidely(next: RuleAppliesWhen, base: RuleAppliesWhen): boolean {
+  if (next.regulated && !base.regulated) return false;
+  if (next.shipCountries && (!base.shipCountries || base.shipCountries.some((c) => !next.shipCountries!.includes(c)))) return false;
+  if (next.regions && (!base.regions || base.regions.some((r) => !next.regions!.includes(r)))) return false;
+  return true;
+}
+
+/**
+ * Throws unless the policy is well formed: unique ids, a named authority and valid duration on every
+ * rule, and every override of a default rule at least as long, at least as wide (groups and
+ * appliesWhen) and still a floor when the default is one.
+ */
+export function validatePolicy(policy: RetentionPolicy = RETENTION_POLICY): void {
+  if (!isPositiveInteger(policy.previewTimeScale)) throw new Error("previewTimeScale must be a positive integer");
+  if (!isPositiveInteger(policy.previewCutoffDays)) throw new Error("previewCutoffDays must be a positive integer");
+  if (!isPositiveInteger(policy.message.daysFromReceived)) throw new Error("message rule needs positive days");
+  const ids = new Set<string>();
+  for (const rule of policy.rules) {
+    validateRuleShape(rule, "default");
+    if (ids.has(rule.id)) throw new Error(`duplicate rule id ${rule.id}`);
+    ids.add(rule.id);
+  }
+  const fulfillment = policy.rules.find((rule) => rule.groups.length === GROUPS.length && rule.duration.kind === "days-after-terminal");
+  if (!fulfillment) throw new Error("the policy needs a terminal-relative rule covering every group");
+  const defaults = new Map(policy.rules.map((rule) => [rule.id, rule]));
+  for (const [tenantId, overrides] of Object.entries(policy.tenantOverrides)) {
+    const seen = new Set<string>();
+    for (const rule of overrides) {
+      const where = `override for ${tenantId}`;
+      validateRuleShape(rule, where);
+      if (seen.has(rule.id)) throw new Error(`${where}: duplicate rule id ${rule.id}`);
+      seen.add(rule.id);
+      const base = defaults.get(rule.id);
+      if (!base) continue;
+      if (base.floor && !rule.floor) throw new Error(`${where}: rule ${rule.id} removes a floor`);
+      if (!durationNotShorter(rule.duration, base.duration)) throw new Error(`${where}: rule ${rule.id} shortens the default`);
+      if (base.groups.some((group) => !rule.groups.includes(group))) throw new Error(`${where}: rule ${rule.id} drops a group`);
+      if (!appliesAtLeastAsWidely(rule.appliesWhen, base.appliesWhen)) throw new Error(`${where}: rule ${rule.id} narrows where it applies`);
+    }
+  }
+}
+
+function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([, child]) => child !== undefined)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([key, child]) => `${JSON.stringify(key)}:${canonicalJson(child)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+const versionCache = new WeakMap<RetentionPolicy, Promise<string>>();
+
+/**
+ * The rule-table version: hex SHA-256 of the canonical JSON of the whole policy. Async because the
+ * Worker runtime offers SHA-256 only through Web Crypto (`crypto.subtle`); memoized per policy.
+ */
+export function ruleVersion(policy: RetentionPolicy = RETENTION_POLICY): Promise<string> {
+  const cached = versionCache.get(policy);
+  if (cached) return cached;
+  const computed = crypto.subtle
+    .digest("SHA-256", new TextEncoder().encode(canonicalJson(policy)))
+    .then((digest) => Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join(""));
+  versionCache.set(policy, computed);
+  return computed;
+}

package/apps/storefront/src/lib/customers/contactVault/zip3.ts

@@ -0,0 +1,24 @@
+/**
+ * Three-digit ZIP areas for the unlinked order facts.
+ *
+ * Follows the HIPAA Safe Harbor de-identification standard, 45 CFR 164.514(b)(2)(i)(B): the initial
+ * three digits of a ZIP code may be kept only where the geographic unit formed by all ZIP codes
+ * sharing them contains more than 20,000 people; every other three-digit area is replaced by 000.
+ * RESTRICTED_ZIP3 is the HHS-published list of three-digit areas at or under 20,000 people.
+ */
+
+export const RESTRICTED_ZIP3: ReadonlySet<string> = new Set([
+  "036", "059", "063", "102", "203", "556", "692", "790", "821", "823", "830", "831", "878", "879", "884", "890", "893",
+]);
+
+const US_ZIP = /^(\d{3})\d{2}(?:-?\d{4})?$/;
+
+/** The de-identified three-digit ZIP area of a US postal code; null for non-US or unreadable codes. */
+export function zip3(postalCode: unknown, country: unknown): string | null {
+  if (typeof country !== "string" || country.trim().toUpperCase() !== "US") return null;
+  if (typeof postalCode !== "string") return null;
+  const match = US_ZIP.exec(postalCode.trim());
+  if (!match) return null;
+  const area = match[1]!;
+  return RESTRICTED_ZIP3.has(area) ? "000" : area;
+}