@bygghammar/cms-platform 0.20.0 → 0.22.0

package/src/server/forms-core.ts

@@ -0,0 +1,820 @@
+/**
+ * Host-agnostic forms server core.
+ *
+ * Every rule that governs form definitions — settings resolution, notification
+ * routing, snapshots, the audit trail and the definition CRUD/version flow —
+ * lives here so that every site behaves identically. Hosts supply a Supabase
+ * compatible client plus the acting user; nothing site-specific is referenced.
+ *
+ * Data-safety invariants preserved here:
+ *  - submissions are never touched by definition changes
+ *  - a field key that already has stored answers can never be removed
+ *  - snapshots and audit entries never block the write they describe
+ */
+import {
+  defaultFieldsFor,
+  mergeFields,
+  type FormDefaults,
+  type FormFieldDef,
+  type FormPrivateSettings,
+  type FormPublicSettings,
+} from "../forms/field-sets";
+import { EMAIL_RE, evaluateRule, normalizePolicyUrl } from "../forms/conditions";
+import { diffForms, summarizeChanges, type FormAuditChange } from "../forms/form-audit";
+import { actorEmail, assertStaff, type PlatformAuthContext } from "./guards";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+export type FormsDb = any;
+
+export type FormsContext = PlatformAuthContext & { supabase: FormsDb };
+
+/* ------------------------------ pure helpers ------------------------------ */
+
+export const pickText = (a: string | undefined | null, b: string | undefined | null) =>
+  (a ?? "").trim() || (b ?? "").trim();
+
+export const pickLocalized = (
+  a: Record<string, string> | undefined,
+  b: Record<string, string> | undefined,
+  locale: string,
+) => {
+  const from = (m?: Record<string, string>) =>
+    (m?.[locale] ?? m?.["sv"] ?? m?.["en"] ?? "").toString().trim();
+  return from(a) || from(b);
+};
+
+/** Everything the submit path needs, with per-form overrides applied. */
+export function effectiveSettings(
+  form: { public_settings: unknown; private_settings: unknown },
+  defaults: FormDefaults | null,
+) {
+  const pub = (form.public_settings ?? {}) as FormPublicSettings;
+  const priv = (form.private_settings ?? {}) as FormPrivateSettings;
+  return {
+    pub,
+    priv,
+    requireConsent: pub.requireConsent !== false,
+    honeypot: defaults?.spam_honeypot !== false,
+    minSeconds: priv.spamMinSeconds ?? defaults?.spam_min_seconds ?? 3,
+    maxPerHour: priv.spamMaxPerHour ?? defaults?.spam_max_per_hour ?? 0,
+    notifyEnabled: priv.notifyEnabled ?? defaults?.notify_enabled ?? true,
+    notifyTo: pickText(priv.notifyTo, defaults?.notify_to),
+    notifyFromName: pickText(priv.notifyFromName, defaults?.notify_from_name),
+    notifyFromEmail: pickText(priv.notifyFromEmail, defaults?.notify_from_email),
+    notifyReplyTo: pickText(priv.notifyReplyTo, defaults?.notify_reply_to),
+    notificationRules: (priv.notificationRules ?? []).filter((r) => r && r.enabled !== false),
+    autoreplyEnabled: priv.autoreplyEnabled ?? defaults?.autoreply_enabled ?? false,
+    sheetId: pickText(priv.sheetId, defaults?.sheet_id),
+    sheetTab: pickText(priv.sheetTab, defaults?.sheet_tab) || "Sheet1",
+    sheetLive: priv.sheetLiveAppend ?? defaults?.sheet_live_append ?? false,
+    savePartials: priv.savePartials ?? defaults?.save_partials ?? true,
+    retentionDays: defaults?.retention_days ?? 0,
+    webhookUrl: (priv.webhookUrl ?? "").trim(),
+    webhookSecret: (priv.webhookSecret ?? "").trim(),
+    webhookEnabled: priv.webhookEnabled !== false && !!(priv.webhookUrl ?? "").trim(),
+  };
+}
+
+export type EffectiveSettings = ReturnType<typeof effectiveSettings>;
+
+/**
+ * Resolve who gets the admin notification for one submission.
+ * Conditional rules add recipients; an "exclusive" match replaces the
+ * standard recipient list entirely (routing instead of copying).
+ */
+export function resolveRecipients(
+  eff: EffectiveSettings,
+  values: Record<string, string>,
+): string {
+  const matched = eff.notificationRules.filter((r) => evaluateRule(r.when, values));
+  const exclusive = matched.filter((r) => r.exclusive);
+  const list = exclusive.length
+    ? exclusive.map((r) => r.to)
+    : [eff.notifyTo, ...matched.map((r) => r.to)];
+  return list.filter(Boolean).join(",");
+}
+
+/** Localized notification subject/body with per-form override then defaults. */
+export function notificationTemplate(
+  eff: EffectiveSettings,
+  defaults: FormDefaults | null,
+  locale: string,
+) {
+  return {
+    subject: pickLocalized(
+      eff.priv.notifySubject as Record<string, string> | undefined,
+      defaults?.notify_subject as Record<string, string> | undefined,
+      locale,
+    ),
+    body: pickLocalized(
+      eff.priv.notifyBody as Record<string, string> | undefined,
+      defaults?.notify_body as Record<string, string> | undefined,
+      locale,
+    ),
+  };
+}
+
+/** Best guess at the submitter's own address: typed email field, then any value. */
+export function submitterEmail(
+  fields: FormFieldDef[],
+  payload: Record<string, string>,
+): string {
+  const emailField = fields.find((f) => f.enabled && f.type === "email");
+  const direct = emailField ? payload[emailField.key] : "";
+  if (direct) return direct;
+  return Object.values(payload).find((v) => EMAIL_RE.test(v)) ?? "";
+}
+
+/** One spreadsheet row for a submission, column order fixed by the field list. */
+export function sheetRow(
+  createdAt: string,
+  formKey: string,
+  locale: string,
+  fields: FormFieldDef[],
+  payload: Record<string, string>,
+) {
+  return [
+    createdAt,
+    formKey,
+    locale,
+    ...fields.filter((f) => f.enabled).map((f) => payload[f.key] ?? ""),
+  ];
+}
+
+/** Collect every `formKey` referenced anywhere inside a block tree. */
+export function collectFormKeys(value: unknown, out: Set<string>) {
+  if (!value || typeof value !== "object") return;
+  if (Array.isArray(value)) {
+    for (const v of value) collectFormKeys(v, out);
+    return;
+  }
+  const obj = value as Record<string, unknown>;
+  if (typeof obj["formKey"] === "string" && obj["formKey"]) out.add(obj["formKey"] as string);
+  for (const v of Object.values(obj)) collectFormKeys(v, out);
+}
+
+/** Field keys that already carry stored answers, from a set of payloads. */
+export function usedFieldKeys(payloads: Array<Record<string, unknown> | null | undefined>) {
+  const used = new Set<string>();
+  for (const payload of payloads) {
+    for (const [k, v] of Object.entries((payload ?? {}) as Record<string, unknown>)) {
+      if (v !== "" && v != null) used.add(k);
+    }
+  }
+  return used;
+}
+
+/* ------------------------- audit + delivery logging ------------------------ */
+
+/**
+ * Append one entry to the shared audit trail. Auditing must never block the
+ * write it describes, so failures are logged and swallowed.
+ */
+export async function logFormAuditCore(
+  context: FormsContext,
+  action: string,
+  entityId: string | null,
+  meta: Record<string, unknown>,
+) {
+  try {
+    await context.supabase.from("audit_logs").insert({
+      actor_id: context.userId,
+      actor_email: actorEmail(context),
+      action,
+      entity: "forms",
+      entity_id: entityId,
+      meta: meta as never,
+    });
+  } catch (e) {
+    console.error("[forms] audit", e);
+  }
+}
+
+export type DeliveryLogEntry = {
+  submissionId?: string | null;
+  formKey: string;
+  channel: "notification" | "autoreply" | "sheet" | "webhook";
+  ok: boolean;
+  target?: string | null;
+  error?: string | null;
+  attempt?: number;
+  durationMs?: number | null;
+  meta?: Record<string, unknown>;
+};
+
+/**
+ * Append-only diagnostics for one delivery attempt. Failures here must never
+ * affect the submission itself, so everything is swallowed.
+ */
+export async function logDeliveryCore(db: FormsDb, entry: DeliveryLogEntry) {
+  try {
+    await db.from("form_delivery_attempts").insert({
+      submission_id: entry.submissionId ?? null,
+      form_key: entry.formKey,
+      channel: entry.channel,
+      status: entry.ok ? "ok" : "failed",
+      target: (entry.target ?? "").slice(0, 400) || null,
+      error: entry.error ? entry.error.slice(0, 1000) : null,
+      attempt: entry.attempt ?? 1,
+      duration_ms: entry.durationMs ?? null,
+      meta: (entry.meta ?? {}) as never,
+      resolved_at: entry.ok ? new Date().toISOString() : null,
+    } as never);
+    // A successful attempt closes every earlier failure on the same channel.
+    if (entry.ok && entry.submissionId) {
+      await db
+        .from("form_delivery_attempts")
+        .update({ resolved_at: new Date().toISOString() } as never)
+        .eq("submission_id", entry.submissionId)
+        .eq("channel", entry.channel)
+        .eq("status", "failed")
+        .is("resolved_at", null);
+    }
+  } catch (e) {
+    console.error("[forms] logDelivery", e);
+  }
+}
+
+/* ------------------------------- definitions ------------------------------ */
+
+export type FormRowCore = {
+  id: string;
+  key: string;
+  name: string;
+  form_type: string;
+  is_active: boolean;
+  fields: FormFieldDef[];
+  public_settings: FormPublicSettings;
+  private_settings: FormPrivateSettings;
+  updated_at: string;
+  submissions: number;
+  newSubmissions: number;
+  lastSubmissionAt: string | null;
+  /** Field keys that already have stored answers — never deletable. */
+  usedFieldKeys: string[];
+};
+
+export async function listFormsCore(context: FormsContext): Promise<FormRowCore[]> {
+  await assertStaff(context);
+  const { data, error } = await context.supabase
+    .from("forms")
+    .select("*")
+    .is("deleted_at", null)
+    .order("name", { ascending: true });
+  if (error) throw new Error(error.message);
+
+  const { data: subs } = await context.supabase
+    .from("form_submissions")
+    .select("form_key, status, created_at, payload")
+    .order("created_at", { ascending: false })
+    .limit(5000);
+
+  const counts = new Map<string, number>();
+  const news = new Map<string, number>();
+  const last = new Map<string, string>();
+  const used = new Map<string, Set<string>>();
+  for (const s of subs ?? []) {
+    counts.set(s.form_key, (counts.get(s.form_key) ?? 0) + 1);
+    if (s.status === "new") news.set(s.form_key, (news.get(s.form_key) ?? 0) + 1);
+    if (!last.has(s.form_key)) last.set(s.form_key, s.created_at);
+    const set = used.get(s.form_key) ?? new Set<string>();
+    for (const k of usedFieldKeys([s.payload as Record<string, unknown>])) set.add(k);
+    used.set(s.form_key, set);
+  }
+
+  return (data ?? []).map((r: any) => ({
+    id: r.id,
+    key: r.key,
+    name: r.name,
+    form_type: r.form_type,
+    is_active: r.is_active,
+    fields: mergeFields(r.form_type, r.fields),
+    public_settings: (r.public_settings ?? {}) as FormPublicSettings,
+    private_settings: (r.private_settings ?? {}) as FormPrivateSettings,
+    updated_at: r.updated_at,
+    submissions: counts.get(r.key) ?? 0,
+    newSubmissions: news.get(r.key) ?? 0,
+    lastSubmissionAt: last.get(r.key) ?? null,
+    usedFieldKeys: Array.from(used.get(r.key) ?? []),
+  }));
+}
+
+/**
+ * Store an immutable snapshot of a form definition. Snapshots are the
+ * rollback surface: they never contain submissions, only the definition.
+ */
+export async function snapshotFormCore(
+  context: FormsContext,
+  form: {
+    id?: string;
+    key: string;
+    name: string;
+    form_type: string;
+    fields: unknown;
+    public_settings: unknown;
+    private_settings: unknown;
+  },
+  note: string,
+) {
+  try {
+    const { data: last } = await context.supabase
+      .from("form_versions")
+      .select("version_no, fields, public_settings, private_settings, name")
+      .eq("form_key", form.key)
+      .order("version_no", { ascending: false })
+      .limit(1)
+      .maybeSingle();
+
+    // Skip no-op saves so history stays readable.
+    if (last) {
+      const same =
+        JSON.stringify(last.fields) === JSON.stringify(form.fields) &&
+        JSON.stringify(last.public_settings) === JSON.stringify(form.public_settings) &&
+        JSON.stringify(last.private_settings) === JSON.stringify(form.private_settings) &&
+        last.name === form.name;
+      if (same) return;
+    }
+
+    await context.supabase.from("form_versions").insert({
+      form_id: form.id ?? null,
+      form_key: form.key,
+      version_no: (last?.version_no ?? 0) + 1,
+      name: form.name,
+      form_type: form.form_type,
+      fields: form.fields as never,
+      public_settings: form.public_settings as never,
+      private_settings: form.private_settings as never,
+      note,
+      created_by: context.userId,
+      created_by_email: actorEmail(context),
+    });
+  } catch (e) {
+    // History must never block saving the form itself.
+    console.error("[forms] snapshotForm", e);
+  }
+}
+
+export type SaveFormInput = {
+  id?: string;
+  key: string;
+  name: string;
+  form_type: string;
+  is_active: boolean;
+  fields: Array<Record<string, unknown>>;
+  public_settings: Record<string, unknown>;
+  private_settings: Record<string, unknown>;
+};
+
+export async function saveFormCore(
+  context: FormsContext,
+  data: SaveFormInput,
+): Promise<{ id: string }> {
+  await assertStaff(context);
+
+  // Never allow a field key that already has answers to disappear.
+  let before: Record<string, unknown> | null = null;
+  if (data.id) {
+    const { data: existing } = await context.supabase
+      .from("forms")
+      .select("*")
+      .eq("id", data.id)
+      .maybeSingle();
+    before = (existing as Record<string, unknown> | null) ?? null;
+    if (existing?.key) {
+      const { data: subs } = await context.supabase
+        .from("form_submissions")
+        .select("payload")
+        .eq("form_key", existing.key)
+        .limit(2000);
+      const used = usedFieldKeys((subs ?? []).map((s: any) => s.payload));
+      const kept = new Set(data.fields.map((f) => String((f as { key?: unknown }).key ?? "")));
+      const dropped = Array.from(used).filter((k) => !kept.has(k));
+      if (dropped.length) {
+        throw new Error(
+          `These fields already have submissions and cannot be removed: ${dropped.join(", ")}. Disable them instead.`,
+        );
+      }
+    }
+  }
+
+  const row = {
+    key: data.key,
+    name: data.name,
+    form_type: data.form_type,
+    is_active: data.is_active,
+    fields: data.fields as never,
+    public_settings: data.public_settings as never,
+    private_settings: data.private_settings as never,
+  };
+  const q = data.id
+    ? context.supabase.from("forms").update(row).eq("id", data.id).select("*").single()
+    : context.supabase.from("forms").insert(row).select("*").single();
+  const { data: saved, error } = await q;
+  if (error) throw new Error(error.message);
+
+  await snapshotFormCore(context, saved, data.id ? "Saved" : "Created");
+  const changes = diffForms(before as never, {
+    key: data.key,
+    name: data.name,
+    form_type: data.form_type,
+    is_active: data.is_active,
+    fields: data.fields,
+    public_settings: data.public_settings,
+    private_settings: data.private_settings,
+  } as never);
+  await logFormAuditCore(context, data.id ? "form.update" : "form.create", saved.id as string, {
+    key: data.key,
+    name: data.name,
+    changes,
+    summary: summarizeChanges(changes),
+    fieldKeys: changes.filter((c) => c.scope === "field" && c.key).map((c) => c.key),
+  });
+  return { id: saved.id as string };
+}
+
+export type FormUsageCore = { pages: string[]; globalSections: string[] };
+
+/** Where a form is referenced on the site (pages + global sections). */
+export async function getFormUsageCore(
+  context: FormsContext,
+  key: string,
+): Promise<FormUsageCore> {
+  await assertStaff(context);
+  const pages: string[] = [];
+  const globalSections: string[] = [];
+
+  const { data: pageRows } = await context.supabase
+    .from("pages")
+    .select("name, key, current_version_id")
+    .is("deleted_at", null);
+  const versionIds = (pageRows ?? [])
+    .map((p: any) => p.current_version_id)
+    .filter(Boolean) as string[];
+  if (versionIds.length) {
+    const { data: versions } = await context.supabase
+      .from("page_versions")
+      .select("id, blocks")
+      .in("id", versionIds);
+    const byId = new Map((versions ?? []).map((v: any) => [v.id, v.blocks]));
+    for (const p of pageRows ?? []) {
+      const keys = new Set<string>();
+      collectFormKeys(byId.get(p.current_version_id), keys);
+      if (keys.has(key)) pages.push(p.name ?? p.key);
+    }
+  }
+
+  const { data: sections } = await context.supabase
+    .from("global_sections")
+    .select("name, key, current_version_id");
+  const gIds = (sections ?? []).map((s: any) => s.current_version_id).filter(Boolean) as string[];
+  if (gIds.length) {
+    const { data: gVersions } = await context.supabase
+      .from("global_section_versions")
+      .select("id, blocks")
+      .in("id", gIds);
+    const byId = new Map((gVersions ?? []).map((v: any) => [v.id, v.blocks]));
+    for (const s of sections ?? []) {
+      const keys = new Set<string>();
+      collectFormKeys(byId.get(s.current_version_id), keys);
+      if (keys.has(key)) globalSections.push(s.name ?? s.key);
+    }
+  }
+
+  return { pages, globalSections };
+}
+
+/** Soft delete: moves the form to the bin. Submissions are never touched. */
+export async function deleteFormCore(context: FormsContext, id: string) {
+  await assertStaff(context);
+  const email = actorEmail(context);
+  const { data: form } = await context.supabase
+    .from("forms")
+    .select("key, name")
+    .eq("id", id)
+    .maybeSingle();
+  const { error } = await context.supabase
+    .from("forms")
+    .update({
+      deleted_at: new Date().toISOString(),
+      deleted_by: context.userId,
+      deleted_by_email: email,
+      is_active: false,
+    })
+    .eq("id", id)
+    .is("deleted_at", null);
+  if (error) throw new Error(error.message);
+  await logFormAuditCore(context, "form.soft_delete", id, {
+    key: form?.key ?? null,
+    name: form?.name ?? null,
+  });
+  return { ok: true as const };
+}
+
+export type DeletedFormRowCore = {
+  id: string;
+  key: string;
+  name: string;
+  form_type: string;
+  deleted_at: string;
+  deleted_by_email: string | null;
+};
+
+export async function listDeletedFormsCore(
+  context: FormsContext,
+): Promise<{ rows: DeletedFormRowCore[]; canPurge: boolean }> {
+  await assertStaff(context);
+  const { data, error } = await context.supabase
+    .from("forms")
+    .select("id, key, name, form_type, deleted_at, deleted_by_email")
+    .not("deleted_at", "is", null)
+    .order("deleted_at", { ascending: false });
+  if (error) throw new Error(error.message);
+  const { data: isSuper } = await context.supabase.rpc("has_role", {
+    _user_id: context.userId,
+    _role: "superadmin",
+  });
+  return { rows: (data ?? []) as DeletedFormRowCore[], canPurge: !!isSuper };
+}
+
+export async function restoreFormCore(context: FormsContext, id: string) {
+  await assertStaff(context);
+  const { data: form } = await context.supabase
+    .from("forms")
+    .select("key, name")
+    .eq("id", id)
+    .maybeSingle();
+  const { error } = await context.supabase
+    .from("forms")
+    .update({ deleted_at: null, deleted_by: null, deleted_by_email: null })
+    .eq("id", id);
+  if (error) throw new Error(error.message);
+  await logFormAuditCore(context, "form.restore", id, {
+    key: form?.key ?? null,
+    name: form?.name ?? null,
+  });
+  return { ok: true as const };
+}
+
+/** Permanent delete from the bin — superadmin only. Submissions are kept. */
+export async function purgeFormCore(context: FormsContext, id: string) {
+  await assertStaff(context);
+  const { data: isSuper, error: roleErr } = await context.supabase.rpc("has_role", {
+    _user_id: context.userId,
+    _role: "superadmin",
+  });
+  if (roleErr) throw new Error(roleErr.message);
+  if (!isSuper) throw new Error("Only a superadmin can permanently delete forms");
+  const { data: form } = await context.supabase
+    .from("forms")
+    .select("key, name, deleted_at")
+    .eq("id", id)
+    .maybeSingle();
+  if (!form?.deleted_at) throw new Error("Move the form to the bin first");
+  // Submissions keep their form_key; the FK is ON DELETE SET NULL so
+  // customer data is never removed with the form definition.
+  const { error } = await context.supabase.from("forms").delete().eq("id", id);
+  if (error) throw new Error(error.message);
+  await logFormAuditCore(context, "form.purge", id, { key: form.key, name: form.name });
+  return { ok: true as const };
+}
+
+export async function createFormFromTypeCore(
+  context: FormsContext,
+  data: { key: string; name: string; form_type: string },
+): Promise<{ id: string }> {
+  await assertStaff(context);
+  const { data: saved, error } = await context.supabase
+    .from("forms")
+    .insert({
+      key: data.key,
+      name: data.name,
+      form_type: data.form_type,
+      fields: defaultFieldsFor(data.form_type) as never,
+      public_settings: {} as never,
+      private_settings: {} as never,
+    })
+    .select("id")
+    .single();
+  if (error) throw new Error(error.message);
+  await logFormAuditCore(context, "form.create", saved.id as string, {
+    key: data.key,
+    name: data.name,
+    summary: `Created ${data.form_type} form “${data.name}”`,
+  });
+  return { id: saved.id as string };
+}
+
+/** Copy a form definition (settings + fields) under a new key. */
+export async function duplicateFormCore(
+  context: FormsContext,
+  data: { id: string; key: string; name: string },
+): Promise<{ id: string; key: string }> {
+  await assertStaff(context);
+  const { data: src, error: e1 } = await context.supabase
+    .from("forms")
+    .select("*")
+    .eq("id", data.id)
+    .single();
+  if (e1) throw new Error(e1.message);
+  const { data: saved, error } = await context.supabase
+    .from("forms")
+    .insert({
+      key: data.key,
+      name: data.name,
+      form_type: src.form_type,
+      is_active: false,
+      fields: src.fields,
+      public_settings: src.public_settings,
+      private_settings: src.private_settings,
+    })
+    .select("id")
+    .single();
+  if (error) throw new Error(error.message);
+  await logFormAuditCore(context, "form.duplicate", saved.id as string, {
+    key: data.key,
+    name: data.name,
+    from: src.key,
+    summary: `Duplicated “${src.name}” (${src.key}) as “${data.name}” (${data.key})`,
+  });
+  return { id: saved.id as string, key: data.key };
+}
+
+/* --------------------------------- defaults ------------------------------- */
+
+export async function getFormDefaultsCore(context: FormsContext): Promise<FormDefaults> {
+  await assertStaff(context);
+  const { data, error } = await context.supabase
+    .from("form_settings")
+    .select("*")
+    .eq("id", true)
+    .maybeSingle();
+  if (error) throw new Error(error.message);
+  return data as unknown as FormDefaults;
+}
+
+/** Read the site-wide defaults with no guard — used by the public submit path. */
+export async function loadFormDefaultsCore(db: FormsDb): Promise<FormDefaults | null> {
+  const { data } = await db.from("form_settings").select("*").eq("id", true).maybeSingle();
+  return (data as unknown as FormDefaults) ?? null;
+}
+
+export async function saveFormDefaultsCore(
+  context: FormsContext,
+  data: Record<string, unknown>,
+) {
+  await assertStaff(context);
+  const patch = { ...data };
+  if (typeof patch["privacy_policy_url"] === "string") {
+    patch["privacy_policy_url"] = normalizePolicyUrl(patch["privacy_policy_url"] as string);
+  }
+  const { data: before } = await context.supabase
+    .from("form_settings")
+    .select("*")
+    .eq("id", true)
+    .maybeSingle();
+  const { error } = await context.supabase
+    .from("form_settings")
+    .update(patch as never)
+    .eq("id", true);
+  if (error) throw new Error(error.message);
+  const prev = (before ?? {}) as Record<string, unknown>;
+  const changes: FormAuditChange[] = Object.keys(patch)
+    .filter((k) => JSON.stringify(prev[k] ?? null) !== JSON.stringify(patch[k] ?? null))
+    .map((k) => ({
+      scope: "settings" as const,
+      label: k,
+      from: JSON.stringify(prev[k] ?? null).slice(0, 160),
+      to: JSON.stringify(patch[k] ?? null).slice(0, 160),
+    }));
+  if (changes.length) {
+    await logFormAuditCore(context, "form.defaults.update", null, {
+      changes,
+      summary: summarizeChanges(changes),
+    });
+  }
+  return { ok: true as const };
+}
+
+/* --------------------------------- activity ------------------------------- */
+
+export type FormActivityRowCore = {
+  id: string;
+  action: string;
+  actor_email: string | null;
+  actor_id: string | null;
+  entity_id: string | null;
+  meta: any;
+  created_at: string;
+};
+
+/**
+ * Activity trail for forms. Without a key it returns every form-related event,
+ * which powers the module-level activity view.
+ */
+export async function listFormActivityCore(
+  context: FormsContext,
+  data: { formKey?: string; limit: number },
+): Promise<FormActivityRowCore[]> {
+  await assertStaff(context);
+  let q = context.supabase
+    .from("audit_logs")
+    .select("id, action, actor_email, actor_id, entity_id, meta, created_at")
+    .like("action", "form.%")
+    .order("created_at", { ascending: false })
+    .limit(data.limit);
+  if (data.formKey) q = q.eq("meta->>key", data.formKey);
+  const { data: rows, error } = await q;
+  if (error) throw new Error(error.message);
+  return (rows ?? []) as FormActivityRowCore[];
+}
+
+/* --------------------------------- versions ------------------------------- */
+
+export async function listFormVersionsCore(
+  context: FormsContext,
+  data: { formKey: string; limit: number },
+) {
+  await assertStaff(context);
+  const { data: rows, error } = await context.supabase
+    .from("form_versions")
+    .select("*")
+    .eq("form_key", data.formKey)
+    .order("version_no", { ascending: false })
+    .limit(data.limit);
+  if (error) throw new Error(error.message);
+  return (rows ?? []).map((r: any) => ({
+    ...r,
+    fields: mergeFields(r.form_type, r.fields),
+    public_settings: (r.public_settings ?? {}) as FormPublicSettings,
+    private_settings: (r.private_settings ?? {}) as FormPrivateSettings,
+  }));
+}
+
+/**
+ * Roll the live form back to an earlier snapshot. The current state is
+ * snapshotted first, so a rollback can itself always be undone, and field
+ * keys that already have answers are never dropped.
+ */
+export async function restoreFormVersionCore(
+  context: FormsContext,
+  versionId: string,
+): Promise<{ ok: true; carriedFields: string[] }> {
+  await assertStaff(context);
+  const { data: v, error } = await context.supabase
+    .from("form_versions")
+    .select("*")
+    .eq("id", versionId)
+    .single();
+  if (error) throw new Error(error.message);
+
+  const { data: form, error: e2 } = await context.supabase
+    .from("forms")
+    .select("*")
+    .eq("key", v.form_key)
+    .maybeSingle();
+  if (e2) throw new Error(e2.message);
+  if (!form) throw new Error("This form no longer exists.");
+
+  // Data safety: keep any field key that already has stored answers.
+  const { data: subs } = await context.supabase
+    .from("form_submissions")
+    .select("payload")
+    .eq("form_key", v.form_key)
+    .limit(2000);
+  const used = usedFieldKeys((subs ?? []).map((s: any) => s.payload));
+
+  const restored = mergeFields(v.form_type, v.fields);
+  const current = mergeFields(form.form_type, form.fields);
+  const keys = new Set(restored.map((f) => f.key));
+  const carried = current
+    .filter((f) => used.has(f.key) && !keys.has(f.key))
+    .map((f) => ({ ...f, enabled: false }));
+
+  await snapshotFormCore(context, form, `Auto-saved before rollback to v${v.version_no}`);
+
+  const { error: e3 } = await context.supabase
+    .from("forms")
+    .update({
+      name: v.name,
+      fields: [...restored, ...carried] as never,
+      public_settings: v.public_settings,
+      private_settings: v.private_settings,
+    })
+    .eq("id", form.id);
+  if (e3) throw new Error(e3.message);
+
+  await snapshotFormCore(
+    context,
+    {
+      ...form,
+      name: v.name,
+      fields: [...restored, ...carried],
+      public_settings: v.public_settings,
+      private_settings: v.private_settings,
+    },
+    `Rolled back to v${v.version_no}`,
+  );
+
+  return { ok: true as const, carriedFields: carried.map((f) => f.key) };
+}