fix: keep historical Loops profiles stable across cutover settings

Author: richiemcilroy

packages/database/loops/lifecycle.ts

@@ -22,6 +22,19 @@ export type LoopsRuntimeConfig = {
 	teammateJoinedAt?: string | null;
 };
 
+export function enrollmentWindow(signupAt: string, config: LoopsRuntimeConfig) {
+	return {
+		recentSignup:
+			config.enrollmentEnabled &&
+			Date.parse(signupAt) >= config.enrollmentAfter.getTime(),
+		recentJoin:
+			config.enrollmentEnabled &&
+			Boolean(config.teammateJoinedAt) &&
+			Date.parse(isoDate(config.teammateJoinedAt ?? "")) >=
+				config.enrollmentAfter.getTime(),
+	};
+}
+
 export function lifecycleUpdate(
 	source: LoopsProfileSource,
 	remote: LifecycleContact,
@@ -42,20 +55,15 @@ export function lifecycleUpdate(
 		!["unsubscribed", "suppressed"].includes(remote.capConsent ?? "");
 	const subscribed =
 		globallySubscribed && remote.mailingLists[config.listId] === true;
-	const recentSignup =
-		Date.parse(profile.capSignupAt) >= config.enrollmentAfter.getTime();
+	const enrollment = enrollmentWindow(profile.capSignupAt, config);
 	const imported = Boolean(remote.capImportedAt);
-	const recentJoin =
-		teammate &&
-		Boolean(config.teammateJoinedAt) &&
-		Date.parse(isoDate(config.teammateJoinedAt ?? "")) >=
-			config.enrollmentAfter.getTime();
 	const eligible =
 		config.enrollmentEnabled &&
 		source.signedUp &&
 		subscribed &&
 		!source.pendingInvite &&
-		((!imported && recentSignup) || recentJoin) &&
+		((!imported && enrollment.recentSignup) ||
+			(teammate && enrollment.recentJoin)) &&
 		audience !== "unknown";
 	const {
 		subscribed: _subscribed,

packages/database/loops/worker.ts

@@ -12,6 +12,7 @@ import {
 	LoopsRequestError,
 } from "./client";
 import {
+	enrollmentWindow,
 	type LifecycleContact,
 	type LoopsRuntimeConfig,
 	lifecycleUpdate,
@@ -263,8 +264,10 @@ export async function runLoopsSync(customerCopy: CustomerCopy) {
 								profile: profileFingerprint(localProfile),
 								signedUp: source.signedUp,
 								pendingInvite: source.pendingInvite,
-								enrollmentEnabled: config.enrollmentEnabled,
-								enrollmentAfter: config.enrollmentAfter.toISOString(),
+								enrollment: enrollmentWindow(
+									localProfile.capSignupAt,
+									jobConfig,
+								),
 								listId: config.listId,
 								teammateJoinedAt: job.teammateJoinedAt,
 							}),

scripts/loops/README.md

@@ -80,6 +80,8 @@ Deploy the generated schema before code that selects the new columns. The unship
 
 With the schema available and test configuration set, `bun scripts/loops/seed.ts` reports how many completed signups would be queued. `--apply` queues them without sending anything. `bun scripts/loops/sync.ts --apply` processes a bounded batch using the same worker as the cron route. Test mode fails closed without an allowlist. Set `LOOPS_SYNC_MODE=production` only as part of the reviewed cutover. Seed old completed accounts once after the final suppression reconciliation; subsequent signups enter the queue through the application.
 
+Sync fingerprints include the contact's effective signup and teammate-join eligibility, rather than the raw enrollment switch or cutoff date. Enabling enrollment or moving a future cutoff does not invalidate every historical profile. A signup or join crossing the cutoff, or disabling an eligible contact's enrollment, still changes its fingerprint and requires synchronization.
+
 ## Independent delivery check
 
 `.github/workflows/loops-safety.yml` runs every five minutes, independently of the Cap cron worker. It is disabled until the repository variable `LOOPS_WATCHDOG_ENABLED` is explicitly set to `true`. Configure GitHub secrets `LOOPS_API_KEY` and `LOOPS_HEALTH_SECRET`, and configure the same health secret in Cap. Scheduled Actions run from the default branch, so this protection is not deployed while the PR remains unmerged.

scripts/loops/lifecycle.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import { customerCopy } from "../../emails/customer-copy";
 import type { LoopsClient } from "../../packages/database/loops/client";
 import {
+	enrollmentWindow,
 	type LifecycleContact,
 	type LoopsRuntimeConfig,
 	lifecycleUpdate,
@@ -21,6 +22,53 @@ const config: LoopsRuntimeConfig = {
 	allowedEmails: new Set([email]),
 };
 
+describe("enrollment fingerprint", () => {
+	test("historical accounts stay unchanged when enrollment is enabled or the future cutoff moves", () => {
+		const signup = "2026-09-10T10:00:00.000Z";
+		const held = enrollmentWindow(signup, {
+			...config,
+			enrollmentEnabled: false,
+		});
+		expect(held).toEqual({ recentSignup: false, recentJoin: false });
+		expect(enrollmentWindow(signup, config)).toEqual(held);
+		expect(
+			enrollmentWindow(signup, {
+				...config,
+				enrollmentAfter: new Date("2026-09-12T00:00:00Z"),
+			}),
+		).toEqual(held);
+	});
+
+	test("eligible signups change when enrollment is disabled or the cutoff crosses their signup", () => {
+		const signup = "2026-09-11T10:00:00.000Z";
+		expect(enrollmentWindow(signup, config)).toEqual({
+			recentSignup: true,
+			recentJoin: false,
+		});
+		expect(
+			enrollmentWindow(signup, { ...config, enrollmentEnabled: false }),
+		).toEqual({ recentSignup: false, recentJoin: false });
+		expect(
+			enrollmentWindow(signup, {
+				...config,
+				enrollmentAfter: new Date("2026-09-11T10:00:00.001Z"),
+			}),
+		).toEqual({ recentSignup: false, recentJoin: false });
+	});
+
+	test("new teammate joins change historical accounts at the exact cutoff", () => {
+		const signup = "2026-09-10T10:00:00.000Z";
+		const joined = { ...config, teammateJoinedAt: "2026-09-11 00:00:00" };
+		expect(enrollmentWindow(signup, joined)).toEqual({
+			recentSignup: false,
+			recentJoin: true,
+		});
+		expect(
+			enrollmentWindow(signup, { ...joined, enrollmentEnabled: false }),
+		).toEqual({ recentSignup: false, recentJoin: false });
+	});
+});
+
 function fixture(): LoopsProfileSource {
 	return {
 		input: {