placementt-core 1.400.985 → 1.400.987

package/src/surveys/registry.ts

@@ -0,0 +1,589 @@
+/* eslint-disable max-len */
+/**
+ * surveys/registry.ts — what makes each survey kind different.
+ *
+ * The engine (functions/src/surveys.ts) and the web hooks are kind-agnostic: they
+ * read behaviour from here. Everything a kind needs that isn't the data shape lives
+ * in one SurveyKindDef — auth mode, who can answer, thread position, message types,
+ * URL builders and email copy.
+ *
+ * Copy rule: the student/parent invite and reminder wording of a MIGRATED kind must
+ * not change. Every string below marked "(migrated)" is lifted character-for-character
+ * from the notifications file it replaces:
+ *   aspirations      ← notifications/aspirations.ts
+ *   leaver*          ← notifications/leavers.ts (incl. CHECKPOINT_COPY)
+ *   alumniCheckIn    ← notifications/alumni.ts
+ *   skills           ← notifications/skillsAssessments.ts
+ * Strings marked "(new)" have no pre-migration equivalent — parent tracks on kinds
+ * that never had one, and the staff heads-up email.
+ *
+ * Core stays UI-free: form components and UniversalAnalyticsPage schemas are
+ * registered web-side, keyed by the same SurveyKind.
+ */
+
+import type {SurveyKind, SurveyRaterType} from "./types";
+import {SURVEY_KINDS_LIST} from "./types";
+
+/** Where survey links point. The notifications files each hardcoded this. */
+export const SURVEY_SITE_BASE_URL = "https://careerthread.co.uk";
+
+/** Prefix a survey path with the site origin. */
+export const absoluteSurveyUrl = (path: string): string => `${SURVEY_SITE_BASE_URL}${path}`;
+
+/** Who an individual email is addressed to (distinct from SurveyRaterType, which is
+ * about which tracks a cycle asks for). */
+export type SurveyAudience = "student"|"parent"|"employer"|"trustedContact";
+
+/** Everything the copy builders can interpolate. */
+export type SurveyCopyContext = {
+    /** The institute's branding name, as getImageColorInstituteForEmail returns it. */
+    instituteName: string,
+    /** The RECIPIENT's forename — who the salutation greets. */
+    forename: string,
+    /** The subject of the survey, when that isn't the recipient (parent/employer/
+     * trusted-contact emails). */
+    studentForename?: string,
+    studentSurname?: string,
+    /** The kind's staff-facing label, for the copy shared across kinds. */
+    surveyLabel?: string,
+};
+
+export type SurveyEmailCopy = {
+    subject: (ctx: SurveyCopyContext) => string,
+    preheader: (ctx: SurveyCopyContext) => string,
+    title: (ctx: SurveyCopyContext) => string,
+    body: (ctx: SurveyCopyContext) => string,
+    button: string,
+    /** Second CTA — only the alumni check-in has one (its one-click "nothing's
+     * changed" reply, which appends the fragment to the same form URL). */
+    secondaryButton?: {title: string, urlFragment: string},
+};
+
+/** Copy variants a kind can define. "invite"/"reminder" are the chain; anything
+ * else is a kind-specific one-off (e.g. the alumni fresh-link email). */
+export type SurveyCopyVariant = "invite"|"reminder";
+
+type CopySet = Partial<Record<SurveyAudience, SurveyEmailCopy>>;
+
+/** Args for the URL builders. Kinds use the subset they need. */
+export type SurveyPathArgs = {
+    kind: SurveyKind,
+    requestId: string,
+    /** Magic-link token, from SurveyRequest.token / parentToken. */
+    token?: string,
+    role?: "student"|"parent",
+    oId?: string,
+    alumniId?: string,
+    /** Legacy skills links: the skillAssessments doc id and its externalKey. */
+    assessmentId?: string,
+    externalKey?: string,
+    rater?: SurveyRaterType,
+};
+
+/** Which field on a request/cycle the legacy emailInteractions docs were keyed by.
+ * Needed by the migration-window dual-read: old interaction docs carry a different
+ * collectionLink + collectionItemId to the ones the engine writes. */
+export type SurveyLegacyItemIdSource = "requestId"|"threadKey"|"uid"|"alumniId";
+
+export type SurveyLegacyRef = {
+    /** emailInteractions.collectionLink used before the cutover. */
+    collectionLink: string,
+    itemIdSource: SurveyLegacyItemIdSource,
+    messageTypes: {invite?: string, reminder?: string, [variant: string]: string|undefined},
+};
+
+export type SurveyKindDef = {
+    kind: SurveyKind,
+    /** Staff-facing name, singular. */
+    label: string,
+    /** Card shown on the student dashboard for an outstanding request. Absent for
+     * kinds with no in-app student surface (alumni check-ins are magic-link only). */
+    studentCard?: {title: string, description: string},
+    /** "account" — the person logs in with their CareerThread account and the form
+     * reads their uid. "magicLink" — no account (or a dead school email), so the
+     * request carries a token. */
+    authMode: "account"|"magicLink",
+    /** Which rater tracks this kind supports. `students` means the subject in
+     * person — for alumniCheckIn that is the alumnus, not a pupil. */
+    raters: Record<SurveyRaterType, boolean>,
+    /** How a parent/guardian participates. "rater" — a parallel response track on
+     * the request, offered when the slot's `parents` toggle is on. "fallback" — only
+     * contacted after the subject ignores their whole chain (alumni trusted contact).
+     * "none" — never contacted. */
+    parentMode: "rater"|"fallback"|"none",
+    /** Staff can submit on the person's behalf. */
+    staffCanCompleteOnBehalf: boolean,
+    /** Which thread this kind belongs to, if any. Cycles in a thread share a
+     * threadKey and supersede each other in threadOrder. */
+    thread?: string,
+    threadOrder?: number,
+    /** Where responses are stored. Skills keeps writing skillAssessments docs
+     * (plan decision D4) so its aggregates and analytics stay untouched; every other
+     * kind stores the payload on the request. */
+    responseStore: "surveyRequests"|"skillAssessments",
+    /** Days after send that the automatic reminder fires. Absent = no cron reminder:
+     * skills has never had one, and alumni check-ins chase via the emailInteractions
+     * reminder chain rather than a per-cycle reminder. */
+    reminderAfterDays?: number,
+    /** Default window before the form link expires. Only aspirations close today. */
+    defaultCloseAfterDays?: number,
+    /** emailInteractions message types the engine writes. */
+    messageTypes: {invite: string, reminder: string, parentInvite: string, parentReminder: string},
+    /** Pre-cutover interaction identity, for the dual-read supersession shim.
+     * Delete with the shim in Phase E. */
+    legacy: SurveyLegacyRef,
+    /** The engine's form URL. */
+    formPath: (args: SurveyPathArgs) => string,
+    /** The URL live emails already point at. Kept working as a redirect forever. */
+    legacyFormPath?: (args: SurveyPathArgs) => string,
+    copy: {invite: CopySet, reminder: CopySet, extra?: {[variant: string]: SurveyEmailCopy}},
+};
+
+// ─── Shared copy ──────────────────────────────────────────────────────────────
+
+const studentFullName = (ctx: SurveyCopyContext) =>
+    `${ctx.studentForename ?? ""} ${ctx.studentSurname ?? ""}`.trim();
+
+/**
+ * (new) The parent track's copy, shared by every kind that doesn't override it —
+ * one template family across kinds, parameterised by the kind's label (D7). Skills
+ * overrides it, since its parent wording predates the engine and must not change.
+ */
+const GENERIC_PARENT_COPY: {invite: SurveyEmailCopy, reminder: SurveyEmailCopy} = {
+    invite: {
+        subject: (ctx) => `${ctx.instituteName} — ${ctx.surveyLabel ?? "a short survey"} for ${ctx.studentForename}`,
+        preheader: () => "It takes a few minutes and helps your child's school plan their next steps.",
+        title: () => "Your view, in a few minutes",
+        body: (ctx) => `${ctx.instituteName} is asking parents and carers to complete a short form about ${ctx.studentForename}.\n\nThere are no right or wrong answers — your view sits alongside ${ctx.studentForename}'s own, and helps the school support them. Tap the button below to start; no login needed.`,
+        button: "Complete the form",
+    },
+    reminder: {
+        subject: (ctx) => `Reminder — ${ctx.surveyLabel ?? "a short survey"} for ${ctx.studentForename}`,
+        preheader: () => "The form closes soon — it only takes a few minutes.",
+        title: () => "Just a reminder",
+        body: (ctx) => `We noticed the short form ${ctx.instituteName} sent about ${ctx.studentForename} hasn't been completed yet.\n\nIt takes a few minutes and there's no login needed — just tap the button below.`,
+        button: "Complete the form",
+    },
+};
+
+/** Context for the staff heads-up email, which is about a cycle rather than a person. */
+export type SurveyHeadsUpContext = {
+    instituteName: string,
+    /** Staff member's forename. */
+    forename: string,
+    /** The cycle's title, or the kind label + slot label. */
+    surveyLabel: string,
+    /** Human date of the scheduled send, e.g. "Monday 14 September". */
+    sendDateLabel: string,
+    /** How many people it will go to. */
+    recipientCount: number,
+    /** 7 or 1. */
+    daysUntilSend: number,
+};
+
+/**
+ * (new) Staff heads-up, sent at T-7 and T-1 before any scheduled send. One template
+ * for every kind. The two buttons are "view the cycle" and "turn auto-send off".
+ */
+export const SURVEY_HEADS_UP_COPY = {
+    subject: (ctx: SurveyHeadsUpContext) =>
+        ctx.daysUntilSend === 1 ?
+            `Tomorrow: ${ctx.surveyLabel} sends to ${ctx.recipientCount} ${ctx.recipientCount === 1 ? "person" : "people"}` :
+            `In ${ctx.daysUntilSend} days: ${ctx.surveyLabel} is scheduled to send`,
+    preheader: (ctx: SurveyHeadsUpContext) => `Nothing to do unless you want to change it — sending ${ctx.sendDateLabel}.`,
+    title: () => "A survey is about to go out",
+    body: (ctx: SurveyHeadsUpContext) =>
+        `${ctx.surveyLabel} is scheduled to send to ${ctx.recipientCount} ${ctx.recipientCount === 1 ? "person" : "people"} on ${ctx.sendDateLabel}.\n\nYou don't need to do anything — it will go out automatically. If the timing or the recipients aren't right, open it below to change them, or turn auto-send off to hold it.`,
+    primaryButton: "View the survey",
+    secondaryButton: "Turn off auto-send",
+};
+
+// ─── Kind definitions ─────────────────────────────────────────────────────────
+
+/** The leaver thread, in send order. */
+export const SURVEY_THREADS: {[thread: string]: SurveyKind[]} = {
+    leaver: ["leaverIntentions", "leaverResults", "leaverChristmas"],
+};
+
+const LEAVER_LEGACY_REF = {collectionLink: "leaverGroups", itemIdSource: "threadKey" as SurveyLegacyItemIdSource};
+
+export const SURVEY_KINDS: Record<SurveyKind, SurveyKindDef> = {
+    skills: {
+        kind: "skills",
+        label: "Skills survey",
+        studentCard: {title: "New Skills Assessment", description: "Click to complete."},
+        authMode: "account",
+        raters: {students: true, parents: true, employers: true, trustedContact: false},
+        parentMode: "rater",
+        staffCanCompleteOnBehalf: true,
+        responseStore: "skillAssessments",
+        messageTypes: {
+            invite: "surveySkillsInvite",
+            reminder: "surveySkillsReminder",
+            parentInvite: "surveySkillsParentInvite",
+            parentReminder: "surveySkillsParentReminder",
+        },
+        legacy: {collectionLink: "users", itemIdSource: "uid", messageTypes: {invite: "skillRequest"}},
+        formPath: ({requestId}) => `/institutes/surveys/skills/${requestId}`,
+        // Students went in-app; parents and employers used the tokenised public form.
+        legacyFormPath: ({rater, oId, assessmentId, externalKey}) => rater === "students" ?
+            `/institutes/skills/${assessmentId}` :
+            `/skillsRequest/${oId}/${assessmentId}/${externalKey}`,
+        copy: {
+            invite: {
+                // (migrated) subject/title/button are shared across raters; only the
+                // preheader and body differ — as in sendSkillsAssessmentRequest.
+                student: {
+                    subject: () => "[Action Required] Complete Skills Assessment",
+                    preheader: () => "Please complete this self-reflection of your skills development",
+                    title: () => "Complete Skills Assessment",
+                    body: () => "Complete this skills questionnaire to assess your transferrable skills and identify areas you could improve. Click the link below to view the questionnaire.",
+                    button: "Complete Assessment",
+                },
+                parent: {
+                    subject: () => "[Action Required] Complete Skills Assessment",
+                    preheader: (ctx) => `Please complete this skills assessment for ${studentFullName(ctx)}`,
+                    title: () => "Complete Skills Assessment",
+                    body: () => "Please support your student's development by completing this short skills assessment that helps us understand how you think your child is progressing. Click the link below to complete the questionnaire.",
+                    button: "Complete Assessment",
+                },
+                employer: {
+                    subject: () => "[Action Required] Complete Skills Assessment",
+                    preheader: (ctx) => `Please provide feedback for ${studentFullName(ctx)}`,
+                    title: () => "Complete Skills Assessment",
+                    body: (ctx) => `Please complete this short questionnaire based on your experience with ${studentFullName(ctx)}. Your feedback will help shape how ${ctx.studentForename} develops their transferrable skills to support their future career. Click the link below to view the skills assessment.`,
+                    button: "Complete Assessment",
+                },
+            },
+            // Skills has never sent an automatic reminder — see reminderAfterDays.
+            reminder: {},
+        },
+    },
+
+    aspirations: {
+        kind: "aspirations",
+        label: "Careers aspirations survey",
+        studentCard: {title: "Career Aspirations Survey", description: "Your school wants to hear about your career aspirations"},
+        authMode: "account",
+        raters: {students: true, parents: true, employers: false, trustedContact: false},
+        parentMode: "rater",
+        staffCanCompleteOnBehalf: true,
+        responseStore: "surveyRequests",
+        reminderAfterDays: 14,
+        defaultCloseAfterDays: 21,
+        messageTypes: {
+            invite: "surveyAspirationsInvite",
+            reminder: "surveyAspirationsReminder",
+            parentInvite: "surveyAspirationsParentInvite",
+            parentReminder: "surveyAspirationsParentReminder",
+        },
+        legacy: {
+            collectionLink: "aspirationRequests",
+            itemIdSource: "requestId",
+            messageTypes: {invite: "aspirationInvite", reminder: "aspirationReminder"},
+        },
+        formPath: ({requestId}) => `/institutes/surveys/aspirations/${requestId}`,
+        legacyFormPath: ({requestId}) => `/app/destinations/students/form/${requestId}`,
+        copy: {
+            invite: {
+                student: {
+                    // (migrated) sendAspirationInviteEmail
+                    subject: (ctx) => `${ctx.instituteName} — share your career aspirations`,
+                    preheader: () => "It only takes a few minutes and helps your school plan for your future.",
+                    title: () => "Tell us about your career aspirations",
+                    body: (ctx) => `${ctx.instituteName} would like to hear about your career interests and ideas for the future.\n\nClick the button below to log in to CareerThread and complete a short form — it takes about 3 minutes. There are no right or wrong answers.`,
+                    button: "Share my aspirations",
+                },
+                parent: GENERIC_PARENT_COPY.invite,
+            },
+            reminder: {
+                student: {
+                    // (migrated) sendAspirationReminderEmail
+                    subject: (ctx) => `Reminder — share your career aspirations with ${ctx.instituteName}`,
+                    preheader: () => "The form closes soon — it only takes a few minutes.",
+                    title: () => "Just a reminder",
+                    body: (ctx) => `We noticed you haven't yet completed the careers aspirations form from ${ctx.instituteName}.\n\nLog in to CareerThread using the link below — the form takes about 3 minutes and closes soon.`,
+                    button: "Complete the form",
+                },
+                parent: GENERIC_PARENT_COPY.reminder,
+            },
+        },
+    },
+
+    leaverIntentions: {
+        kind: "leaverIntentions",
+        label: "Leaver transition form",
+        studentCard: {title: "Leaver Form", description: "Tell us what you're planning to do next"},
+        authMode: "account",
+        raters: {students: true, parents: true, employers: false, trustedContact: false},
+        parentMode: "rater",
+        staffCanCompleteOnBehalf: true,
+        thread: "leaver",
+        threadOrder: 1,
+        responseStore: "surveyRequests",
+        reminderAfterDays: 14,
+        messageTypes: {
+            invite: "surveyLeaverIntentionsInvite",
+            reminder: "surveyLeaverIntentionsReminder",
+            parentInvite: "surveyLeaverIntentionsParentInvite",
+            parentReminder: "surveyLeaverIntentionsParentReminder",
+        },
+        legacy: {...LEAVER_LEGACY_REF, messageTypes: {invite: "leaverInvite", reminder: "leaverReminder"}},
+        formPath: ({requestId}) => `/institutes/surveys/leaverIntentions/${requestId}`,
+        legacyFormPath: ({requestId}) => `/institutes/leaver/${requestId}`,
+        copy: {
+            invite: {
+                student: {
+                    // (migrated) sendLeaverInviteEmail
+                    subject: (ctx) => `${ctx.instituteName} — tell us your next step`,
+                    preheader: () => "A few minutes now helps your school report your destination and stay in touch.",
+                    title: () => "Before you leave — tell us your plans",
+                    body: (ctx) => `As you get ready to leave ${ctx.instituteName}, please complete a short form telling us what you're planning to do next.\n\nIt takes about 5 minutes and helps your school keep your records up to date. If you'd like to, you can also choose to stay connected as an alumnus.`,
+                    button: "Complete my leaver form",
+                },
+                parent: GENERIC_PARENT_COPY.invite,
+            },
+            reminder: {
+                student: {
+                    // (migrated) sendLeaverReminderEmail
+                    subject: (ctx) => `Reminder — tell ${ctx.instituteName} your next step`,
+                    preheader: () => "Complete your leaver form before you lose access to your school account.",
+                    title: () => "Just a reminder",
+                    body: (ctx) => `We noticed you haven't yet completed your leaver form from ${ctx.instituteName}.\n\nLog in to CareerThread using the link below — it takes about 5 minutes. Once you leave, your school account is deactivated, so it's worth doing now.`,
+                    button: "Complete my leaver form",
+                },
+                parent: GENERIC_PARENT_COPY.reminder,
+            },
+        },
+    },
+
+    leaverResults: {
+        kind: "leaverResults",
+        label: "Results day check-in",
+        studentCard: {title: "Results Day Check-in", description: "Now you have your results, tell us what you're actually doing next"},
+        // The school email is deactivated by results day, so these go to the personal
+        // address captured on the intentions form and authenticate by token.
+        authMode: "magicLink",
+        raters: {students: true, parents: true, employers: false, trustedContact: false},
+        parentMode: "rater",
+        staffCanCompleteOnBehalf: true,
+        thread: "leaver",
+        threadOrder: 2,
+        responseStore: "surveyRequests",
+        reminderAfterDays: 7,
+        messageTypes: {
+            invite: "surveyLeaverResultsInvite",
+            reminder: "surveyLeaverResultsReminder",
+            parentInvite: "surveyLeaverResultsParentInvite",
+            parentReminder: "surveyLeaverResultsParentReminder",
+        },
+        legacy: {...LEAVER_LEGACY_REF, messageTypes: {invite: "leaverResultsInvite", reminder: "leaverResultsReminder"}},
+        formPath: ({requestId, token, role}) =>
+            `/survey/leaverResults/${requestId}?token=${token ?? ""}&role=${role ?? "student"}`,
+        legacyFormPath: ({requestId, token}) => `/leaverCheckpoint/${requestId}/resultsDay/${token ?? ""}`,
+        copy: {
+            invite: {
+                student: {
+                    // (migrated) CHECKPOINT_COPY.resultsDay
+                    subject: (ctx) => `Congratulations from ${ctx.instituteName} — what's next?`,
+                    preheader: () => "Now you have your results, tell us what you're actually doing. It takes 2 minutes.",
+                    title: () => "Congratulations on finishing!",
+                    body: (ctx) => `Now you've got your results, ${ctx.instituteName} would love to know what you're actually doing next.\n\nIt takes about 2 minutes and there's no login needed — just tap the button below. Whatever you've decided, we'd love to hear it.`,
+                    button: "Tell us what's next",
+                },
+                parent: GENERIC_PARENT_COPY.invite,
+            },
+            reminder: {
+                student: {
+                    // (migrated) sendLeaverCheckpointReminderEmail — its subject was built
+                    // from the invite button, lowercased.
+                    subject: (ctx) => `Reminder — tell us what's next with ${ctx.instituteName}`,
+                    preheader: () => "Now you have your results, tell us what you're actually doing. It takes 2 minutes.",
+                    title: () => "Just a reminder",
+                    body: (ctx) => `We noticed you haven't yet had a chance to update ${ctx.instituteName} on what you're doing.\n\nIt only takes 2 minutes, and there's no login needed — just tap the button below.`,
+                    button: "Tell us what's next",
+                },
+                parent: GENERIC_PARENT_COPY.reminder,
+            },
+        },
+    },
+
+    leaverChristmas: {
+        kind: "leaverChristmas",
+        label: "Christmas check-in",
+        studentCard: {title: "Christmas Check-in", description: "Let your school know how you're getting on since you left"},
+        authMode: "magicLink",
+        raters: {students: true, parents: true, employers: false, trustedContact: false},
+        parentMode: "rater",
+        staffCanCompleteOnBehalf: true,
+        thread: "leaver",
+        threadOrder: 3,
+        responseStore: "surveyRequests",
+        reminderAfterDays: 7,
+        messageTypes: {
+            invite: "surveyLeaverChristmasInvite",
+            reminder: "surveyLeaverChristmasReminder",
+            parentInvite: "surveyLeaverChristmasParentInvite",
+            parentReminder: "surveyLeaverChristmasParentReminder",
+        },
+        legacy: {...LEAVER_LEGACY_REF, messageTypes: {invite: "leaverChristmasInvite", reminder: "leaverChristmasReminder"}},
+        formPath: ({requestId, token, role}) =>
+            `/survey/leaverChristmas/${requestId}?token=${token ?? ""}&role=${role ?? "student"}`,
+        legacyFormPath: ({requestId, token}) => `/leaverCheckpoint/${requestId}/christmas/${token ?? ""}`,
+        copy: {
+            invite: {
+                student: {
+                    // (migrated) CHECKPOINT_COPY.christmas
+                    subject: (ctx) => `Quick check-in from ${ctx.instituteName} — how's it going?`,
+                    preheader: () => "Still 2 minutes — let us know how you're getting on since you left.",
+                    title: () => "How's it going since you left?",
+                    body: (ctx) => `It's been a few months since you left ${ctx.instituteName}, so we wanted to check in.\n\nAre you still doing what you planned, or has something changed? Either way it's completely fine — just let us know so we can keep your records up to date. It takes about 2 minutes, no login needed.`,
+                    button: "Quick check-in",
+                },
+                parent: GENERIC_PARENT_COPY.invite,
+            },
+            reminder: {
+                student: {
+                    // (migrated) sendLeaverCheckpointReminderEmail
+                    subject: (ctx) => `Reminder — quick check-in with ${ctx.instituteName}`,
+                    preheader: () => "Still 2 minutes — let us know how you're getting on since you left.",
+                    title: () => "Just a reminder",
+                    body: (ctx) => `We noticed you haven't yet had a chance to update ${ctx.instituteName} on what you're doing.\n\nIt only takes 2 minutes, and there's no login needed — just tap the button below.`,
+                    button: "Quick check-in",
+                },
+                parent: GENERIC_PARENT_COPY.reminder,
+            },
+        },
+    },
+
+    alumniCheckIn: {
+        kind: "alumniCheckIn",
+        label: "Alumni check-in",
+        // No student dashboard card — alumni have no CareerThread account.
+        authMode: "magicLink",
+        raters: {students: true, parents: false, employers: false, trustedContact: true},
+        parentMode: "fallback",
+        staffCanCompleteOnBehalf: true,
+        responseStore: "surveyRequests",
+        // Chased by the emailInteractions reminder chain, which escalates to the
+        // trusted contact, rather than by a per-cycle reminder.
+        messageTypes: {
+            invite: "surveyAlumniCheckInInvite",
+            reminder: "surveyAlumniCheckInReminder",
+            parentInvite: "surveyAlumniCheckInTrustedContact",
+            parentReminder: "surveyAlumniCheckInTrustedContactReminder",
+        },
+        legacy: {
+            collectionLink: "alumni",
+            itemIdSource: "alumniId",
+            messageTypes: {
+                invite: "alumniCheckInInvite",
+                trustedContact: "alumniCheckInTrustedContact",
+                linkRefresh: "alumniCheckInLinkRefresh",
+            },
+        },
+        formPath: ({requestId, token, role}) =>
+            `/survey/alumniCheckIn/${requestId}?token=${token ?? ""}&role=${role ?? "student"}`,
+        legacyFormPath: ({alumniId, token}) => `/alumniCheckIn/${alumniId}/${token ?? ""}`,
+        copy: {
+            invite: {
+                student: {
+                    // (migrated) sendAlumniCheckInInviteEmail — note the plain hyphens,
+                    // which this copy uses where the leaver copy uses en dashes.
+                    subject: (ctx) => `Where are you now? A catch-up from ${ctx.instituteName}`,
+                    preheader: () => "One click if nothing's changed - two minutes if it has.",
+                    title: () => "Where has your journey taken you?",
+                    body: (ctx) => `We love keeping up with where our former students end up. Let us know what you're doing now - it takes about two minutes, and if nothing has changed since we last spoke it's a single click. You can also choose whether to share your journey with our current students, to show them where life after ${ctx.instituteName} can lead.`,
+                    button: "Update my profile",
+                    secondaryButton: {title: "I'm in the same place", urlFragment: "#noChange"},
+                },
+                trustedContact: {
+                    // (migrated) sendTrustedContactCheckInFallbackEmail. Minimum
+                    // disclosure: the alumnus's forename only.
+                    subject: (ctx) => `A quick favour from ${ctx.instituteName}`,
+                    preheader: (ctx) => `Could you tell us how ${ctx.studentForename} is getting on? It takes a minute.`,
+                    title: (ctx) => `How is ${ctx.studentForename} getting on?`,
+                    body: (ctx) => `We're the careers team at ${ctx.instituteName}. We've been trying to reach ${ctx.studentForename} for our annual catch-up but haven't heard back. As their nominated contact, could you let us know what they're doing now? It takes about a minute, and there's no login needed.`,
+                    button: "Tell us how they're doing",
+                },
+            },
+            reminder: {},
+            extra: {
+                // (migrated) sendAlumniCheckInFreshLinkEmail — sent when someone
+                // returns to a used or expired link.
+                linkRefresh: {
+                    subject: (ctx) => `Your fresh profile link from ${ctx.instituteName}`,
+                    preheader: () => "Here's a new secure link to your alumni profile.",
+                    title: () => "Here's a fresh link",
+                    body: () => "The link you followed had expired, so we've sent you this new one. Click below to view or update your alumni profile.",
+                    button: "Open my profile",
+                },
+            },
+        },
+    },
+};
+
+// ─── Lookups ──────────────────────────────────────────────────────────────────
+
+export const surveyKindDef = (kind: SurveyKind): SurveyKindDef => SURVEY_KINDS[kind];
+
+export const isSurveyKind = (value: unknown): value is SurveyKind =>
+    typeof value === "string" && (SURVEY_KINDS_LIST as string[]).includes(value);
+
+/** The kinds in a kind's thread, in send order. A kind with no thread is alone. */
+export const surveyThreadKinds = (kind: SurveyKind): SurveyKind[] => {
+    const thread = SURVEY_KINDS[kind].thread;
+    return thread ? SURVEY_THREADS[thread] : [kind];
+};
+
+/**
+ * Kinds that come LATER in this kind's thread. Their having been sent is what makes
+ * chasing this one pointless — replaces the hand-maintained SUPERSEDES_INTENTIONS /
+ * SUPERSEDES_RESULTS constants in notifications/leavers.ts.
+ */
+export const supersedingSurveyKinds = (kind: SurveyKind): SurveyKind[] => {
+    const order = SURVEY_KINDS[kind].threadOrder;
+    if (!order) return [];
+    return surveyThreadKinds(kind)
+        .filter((k) => (SURVEY_KINDS[k].threadOrder ?? 0) > order);
+};
+
+/**
+ * Message types to pass as Email.sendEmail's `supersededBy` — if any has already
+ * gone to this person for this thread, the email being built is skipped.
+ *
+ * Only covers thread supersession. Same-kind supersession (a newer cycle to the same
+ * person, plan decision D8) can't be expressed this way, because each cycle is its
+ * own collection item — the engine stamps `supersededAt` on the older request and
+ * skips it instead.
+ */
+export const supersedingMessageTypes = (kind: SurveyKind): string[] =>
+    supersedingSurveyKinds(kind).flatMap((k) =>
+        [SURVEY_KINDS[k].messageTypes.invite, SURVEY_KINDS[k].messageTypes.reminder]);
+
+/**
+ * The same list in pre-cutover message types. Interaction docs written before the
+ * cutover carry these AND a different collectionLink (see legacy.collectionLink), so
+ * the engine needs a second supersession query against them for one release. Both
+ * this and the dual-read go in Phase E.
+ */
+export const legacySupersedingMessageTypes = (kind: SurveyKind): string[] =>
+    supersedingSurveyKinds(kind).flatMap((k) => {
+        const legacy = SURVEY_KINDS[k].legacy.messageTypes;
+        return [legacy.invite, legacy.reminder].filter((t): t is string => Boolean(t));
+    });
+
+/**
+ * The copy for one email, falling back to the shared parent template for kinds that
+ * don't override it. Returns undefined when a kind deliberately has no such email
+ * (skills sends no reminders; alumni check-ins re-send the invite instead).
+ */
+export const surveyEmailCopy = (
+    kind: SurveyKind, audience: SurveyAudience, variant: SurveyCopyVariant,
+): SurveyEmailCopy|undefined => {
+    const def = SURVEY_KINDS[kind];
+    const own = def.copy[variant][audience];
+    if (own) return own;
+    if (audience === "parent" && def.parentMode === "rater") return GENERIC_PARENT_COPY[variant];
+    return undefined;
+};