@aglyn/aglyn 1.0.0-beta.200 → 1.0.0-beta.202

package/src/lib/app-utils/email-state.d.ts

@@ -15,10 +15,14 @@
  * limitations under the License.
  */
 /** Every state, weakest first. */
-export declare const EMAIL_STATE_STATUSES: readonly ["ok", "bounced", "blocked", "unsubscribed", "complained", "do_not_contact"];
+export declare const EMAIL_STATE_STATUSES: readonly ["ok", "undeliverable", "bounced", "blocked", "unsubscribed", "complained", "do_not_contact"];
 export type EmailStateStatus = (typeof EMAIL_STATE_STATUSES)[number];
-/** Which sender's verdict it is. */
-export type EmailStateSource = 'sequence' | 'campaign' | 'member';
+/**
+ * Which sender's verdict it is. `check` is the deliverability check
+ * (AGL-3328), which reads the domain's DNS when the record is captured and
+ * before a send, and says what it found before anything bounces.
+ */
+export type EmailStateSource = 'sequence' | 'campaign' | 'member' | 'check';
 /** The field on the lead and the contact. */
 export declare const EMAIL_STATE_FIELD = "emailState";
 export interface EmailState {

package/src/lib/app-utils/email-state.js

@@ -37,15 +37,28 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * overwrites a refusal on its own: the ranking below decides.
  *==========================================*/ /** Every state, weakest first. */ export const EMAIL_STATE_STATUSES = [
     /** The address may be emailed: released, or confirmed again. */ 'ok',
+    /**
+   * Mail to it WOULD bounce: its domain has no mail server, or publishes a
+   * null MX (AGL-3328). A prediction from DNS rather than a bounce, so the
+   * weakest refusal: any real verdict replaces it, and the check clears it
+   * when the domain starts taking mail.
+   */ 'undeliverable',
     /** Mail to it bounced for good: the mailbox does not exist. */ 'bounced',
     /** The recipient's mail gateway refused the sender on policy or reputation. */ 'blocked',
     /** The unsubscribe link or header was used. */ 'unsubscribed',
     /** A reply called the email spam, or the recipient reported it. */ 'complained',
     /** On the organization's do-not-contact list — a member's or the runtime's entry. */ 'do_not_contact'
 ];
+const EMAIL_STATE_SOURCES = [
+    'sequence',
+    'campaign',
+    'member',
+    'check'
+];
 /** The field on the lead and the contact. */ export const EMAIL_STATE_FIELD = 'emailState';
 /** How a state reads on the chip — typed so a state cannot ship unlabeled. */ export const EMAIL_STATE_LABELS = {
     ok: 'Email OK',
+    undeliverable: 'Would bounce',
     bounced: 'Bounced',
     blocked: 'Blocked by their mail gateway',
     unsubscribed: 'Unsubscribed',
@@ -60,11 +73,12 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * over nothing — a release is written on purpose, by a path that forces it.
  */ const EMAIL_STATE_RANK = {
     ok: 0,
-    bounced: 1,
-    blocked: 2,
-    unsubscribed: 3,
-    complained: 4,
-    do_not_contact: 5
+    undeliverable: 1,
+    bounced: 2,
+    blocked: 3,
+    unsubscribed: 4,
+    complained: 5,
+    do_not_contact: 6
 };
 export function isEmailStateStatus(value) {
     return typeof value === 'string' && EMAIL_STATE_STATUSES.includes(value);
@@ -80,7 +94,7 @@ export function isEmailStateStatus(value) {
     return _extends({
         status: state['status'],
         atMs: Number.isFinite(atMs) && atMs > 0 ? atMs : 0,
-        source: source === 'sequence' || source === 'campaign' || source === 'member' ? source : 'campaign',
+        source: EMAIL_STATE_SOURCES.includes(source) ? source : 'campaign',
         detail: typeof state['detail'] === 'string' && state['detail'] ? state['detail'] : null
     }, enrollmentId ? {
         enrollmentId
@@ -118,6 +132,8 @@ export function isEmailStateStatus(value) {
     const since = when ? ` on ${when}` : '';
     const said = state.detail ? ` ${state.detail}` : '';
     switch(state.status){
+        case 'undeliverable':
+            return `Email to this address would bounce: its domain has no mail server${since ? ` (checked${since})` : ''}.${said}`;
         case 'bounced':
             return `Email to this address bounced${since}: the mailbox does not exist.${said}`;
         case 'blocked':

package/src/lib/app-utils/email-state.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/email-state.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/*==========================================\n * A RECORD'S EMAIL STATE (AGL-3245).\n *\n * The lists the senders consult — the platform suppression list, a site's\n * suppressions, an organization's do-not-contact list — are keyed by a\n * hash nobody can read. The record a person opens is the lead or the\n * contact, and until now it said nothing: an address that hard-bounced at\n * 10:30 still read as \"Sent\" at 12:30, and a member reading it would have\n * emailed the person again by hand.\n *\n * So the record carries `emailState`: what the last verdict on its address\n * was, when, from which sender, and in the sender's own words. It is\n * WRITTEN BY THE PLATFORM ONLY — the outreach runtime, the campaign\n * webhook, a member's do-not-contact mark — never by a form, an import or\n * the record's own editor, and the rules hold clients off the field. It\n * is a mirror of the lists, not a list: a send still asks the lists, and\n * the record says what they hold in words a person can act on.\n *\n * Absent means nothing is known. `ok` is a verdict too — a release, a\n * confirmed re-subscription — and it is the one state that never\n * overwrites a refusal on its own: the ranking below decides.\n *==========================================*/\n\n/** Every state, weakest first. */\nexport const EMAIL_STATE_STATUSES = [\n  /** The address may be emailed: released, or confirmed again. */\n  'ok',\n  /** Mail to it bounced for good: the mailbox does not exist. */\n  'bounced',\n  /** The recipient's mail gateway refused the sender on policy or reputation. */\n  'blocked',\n  /** The unsubscribe link or header was used. */\n  'unsubscribed',\n  /** A reply called the email spam, or the recipient reported it. */\n  'complained',\n  /** On the organization's do-not-contact list — a member's or the runtime's entry. */\n  'do_not_contact',\n] as const\n\nexport type EmailStateStatus = (typeof EMAIL_STATE_STATUSES)[number]\n\n/** Which sender's verdict it is. */\nexport type EmailStateSource = 'sequence' | 'campaign' | 'member'\n\n/** The field on the lead and the contact. */\nexport const EMAIL_STATE_FIELD = 'emailState'\n\nexport interface EmailState {\n  status: EmailStateStatus\n  /** When the verdict was given, epoch ms. */\n  atMs: number\n  source: EmailStateSource\n  /** The sender's own words: the bounce's diagnostic, a member's note. */\n  detail: string | null\n  /** The sequence enrollment it came from, when one did. */\n  enrollmentId?: string\n}\n\n/** How a state reads on the chip — typed so a state cannot ship unlabeled. */\nexport const EMAIL_STATE_LABELS: Record<EmailStateStatus, string> = {\n  ok: 'Email OK',\n  bounced: 'Bounced',\n  blocked: 'Blocked by their mail gateway',\n  unsubscribed: 'Unsubscribed',\n  complained: 'Marked as spam',\n  do_not_contact: 'Do not contact',\n}\n\n/**\n * The rank a later verdict must reach to replace an earlier one. A member's\n * do-not-contact mark stands over every automatic verdict; a complaint\n * over an unsubscribe, which is the person's own act over a server's; a\n * block over a bounce, since the block names the whole domain; and `ok`\n * over nothing — a release is written on purpose, by a path that forces it.\n */\nconst EMAIL_STATE_RANK: Record<EmailStateStatus, number> = {\n  ok: 0,\n  bounced: 1,\n  blocked: 2,\n  unsubscribed: 3,\n  complained: 4,\n  do_not_contact: 5,\n}\n\nexport function isEmailStateStatus(value: unknown): value is EmailStateStatus {\n  return typeof value === 'string' && (EMAIL_STATE_STATUSES as readonly string[]).includes(value)\n}\n\n/** The state a record holds, held to its shape, or `null` when it holds none. */\nexport function readEmailState(record: Record<string, unknown> | null | undefined): EmailState | null {\n  const raw = record?.[EMAIL_STATE_FIELD]\n  if (!raw || typeof raw !== 'object') return null\n  const state = raw as Record<string, unknown>\n  if (!isEmailStateStatus(state['status'])) return null\n  const atMs = Number(state['atMs'])\n  const source = state['source']\n  const enrollmentId = typeof state['enrollmentId'] === 'string' && state['enrollmentId'] ? state['enrollmentId'] : undefined\n  return {\n    status: state['status'],\n    atMs: Number.isFinite(atMs) && atMs > 0 ? atMs : 0,\n    source: source === 'sequence' || source === 'campaign' || source === 'member' ? source : 'campaign',\n    detail: typeof state['detail'] === 'string' && state['detail'] ? state['detail'] : null,\n    ...(enrollmentId ? { enrollmentId } : {}),\n  }\n}\n\n/** Whether the state means the address must not be emailed by hand. */\nexport function emailStateForbidsEmail(state: EmailState | null | undefined): boolean {\n  return Boolean(state) && state?.status !== 'ok'\n}\n\n/**\n * The state a record holds after one more verdict: the incoming one when it\n * ranks at least as high as the current — a fresh bounce replaces an old\n * one, a block replaces a bounce, a member's mark replaces anything — else\n * the current. `force` writes the incoming state whatever stands, which is\n * how a release lands.\n */\nexport function nextEmailState(\n  current: EmailState | null | undefined,\n  incoming: EmailState,\n  options: { force?: boolean } = {},\n): EmailState {\n  if (!current || options.force) return incoming\n  return EMAIL_STATE_RANK[incoming.status] >= EMAIL_STATE_RANK[current.status] ? incoming : current\n}\n\n/** When the verdict was given, as the chip's tooltip and the refusal say it. */\nexport function emailStateWhen(state: Pick<EmailState, 'atMs'>): string {\n  if (!state.atMs) return ''\n  try {\n    return new Intl.DateTimeFormat('en-US', { dateStyle: 'medium' }).format(state.atMs)\n  } catch {\n    return new Date(state.atMs).toDateString()\n  }\n}\n\n/**\n * Why the record must not be emailed, in one sentence a disabled button or\n * a refused enrollment can show — or `null` when it may be.\n */\nexport function emailStateRefusal(state: EmailState | null | undefined): string | null {\n  if (!state || !emailStateForbidsEmail(state)) return null\n  const when = emailStateWhen(state)\n  const since = when ? ` on ${when}` : ''\n  const said = state.detail ? ` ${state.detail}` : ''\n  switch (state.status) {\n    case 'bounced':\n      return `Email to this address bounced${since}: the mailbox does not exist.${said}`\n    case 'blocked':\n      return `Their mail gateway blocked email to this address${since}.${said}`\n    case 'unsubscribed':\n      return `They unsubscribed${since}.${said}`\n    case 'complained':\n      return `They marked an email as spam${since}.${said}`\n    case 'do_not_contact':\n      return `On the do-not-contact list${since}.${said}`\n    default:\n      return null\n  }\n}\n"],"names":["EMAIL_STATE_STATUSES","EMAIL_STATE_FIELD","EMAIL_STATE_LABELS","ok","bounced","blocked","unsubscribed","complained","do_not_contact","EMAIL_STATE_RANK","isEmailStateStatus","value","includes","readEmailState","record","raw","state","atMs","Number","source","enrollmentId","undefined","status","isFinite","detail","emailStateForbidsEmail","Boolean","nextEmailState","current","incoming","options","force","emailStateWhen","Intl","DateTimeFormat","dateStyle","format","Date","toDateString","emailStateRefusal","when","since","said"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/email-state.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/*==========================================\n * A RECORD'S EMAIL STATE (AGL-3245).\n *\n * The lists the senders consult — the platform suppression list, a site's\n * suppressions, an organization's do-not-contact list — are keyed by a\n * hash nobody can read. The record a person opens is the lead or the\n * contact, and until now it said nothing: an address that hard-bounced at\n * 10:30 still read as \"Sent\" at 12:30, and a member reading it would have\n * emailed the person again by hand.\n *\n * So the record carries `emailState`: what the last verdict on its address\n * was, when, from which sender, and in the sender's own words. It is\n * WRITTEN BY THE PLATFORM ONLY — the outreach runtime, the campaign\n * webhook, a member's do-not-contact mark — never by a form, an import or\n * the record's own editor, and the rules hold clients off the field. It\n * is a mirror of the lists, not a list: a send still asks the lists, and\n * the record says what they hold in words a person can act on.\n *\n * Absent means nothing is known. `ok` is a verdict too — a release, a\n * confirmed re-subscription — and it is the one state that never\n * overwrites a refusal on its own: the ranking below decides.\n *==========================================*/\n\n/** Every state, weakest first. */\nexport const EMAIL_STATE_STATUSES = [\n  /** The address may be emailed: released, or confirmed again. */\n  'ok',\n  /**\n   * Mail to it WOULD bounce: its domain has no mail server, or publishes a\n   * null MX (AGL-3328). A prediction from DNS rather than a bounce, so the\n   * weakest refusal: any real verdict replaces it, and the check clears it\n   * when the domain starts taking mail.\n   */\n  'undeliverable',\n  /** Mail to it bounced for good: the mailbox does not exist. */\n  'bounced',\n  /** The recipient's mail gateway refused the sender on policy or reputation. */\n  'blocked',\n  /** The unsubscribe link or header was used. */\n  'unsubscribed',\n  /** A reply called the email spam, or the recipient reported it. */\n  'complained',\n  /** On the organization's do-not-contact list — a member's or the runtime's entry. */\n  'do_not_contact',\n] as const\n\nexport type EmailStateStatus = (typeof EMAIL_STATE_STATUSES)[number]\n\n/**\n * Which sender's verdict it is. `check` is the deliverability check\n * (AGL-3328), which reads the domain's DNS when the record is captured and\n * before a send, and says what it found before anything bounces.\n */\nexport type EmailStateSource = 'sequence' | 'campaign' | 'member' | 'check'\n\nconst EMAIL_STATE_SOURCES: readonly EmailStateSource[] = ['sequence', 'campaign', 'member', 'check']\n\n/** The field on the lead and the contact. */\nexport const EMAIL_STATE_FIELD = 'emailState'\n\nexport interface EmailState {\n  status: EmailStateStatus\n  /** When the verdict was given, epoch ms. */\n  atMs: number\n  source: EmailStateSource\n  /** The sender's own words: the bounce's diagnostic, a member's note. */\n  detail: string | null\n  /** The sequence enrollment it came from, when one did. */\n  enrollmentId?: string\n}\n\n/** How a state reads on the chip — typed so a state cannot ship unlabeled. */\nexport const EMAIL_STATE_LABELS: Record<EmailStateStatus, string> = {\n  ok: 'Email OK',\n  undeliverable: 'Would bounce',\n  bounced: 'Bounced',\n  blocked: 'Blocked by their mail gateway',\n  unsubscribed: 'Unsubscribed',\n  complained: 'Marked as spam',\n  do_not_contact: 'Do not contact',\n}\n\n/**\n * The rank a later verdict must reach to replace an earlier one. A member's\n * do-not-contact mark stands over every automatic verdict; a complaint\n * over an unsubscribe, which is the person's own act over a server's; a\n * block over a bounce, since the block names the whole domain; and `ok`\n * over nothing — a release is written on purpose, by a path that forces it.\n */\nconst EMAIL_STATE_RANK: Record<EmailStateStatus, number> = {\n  ok: 0,\n  undeliverable: 1,\n  bounced: 2,\n  blocked: 3,\n  unsubscribed: 4,\n  complained: 5,\n  do_not_contact: 6,\n}\n\nexport function isEmailStateStatus(value: unknown): value is EmailStateStatus {\n  return typeof value === 'string' && (EMAIL_STATE_STATUSES as readonly string[]).includes(value)\n}\n\n/** The state a record holds, held to its shape, or `null` when it holds none. */\nexport function readEmailState(record: Record<string, unknown> | null | undefined): EmailState | null {\n  const raw = record?.[EMAIL_STATE_FIELD]\n  if (!raw || typeof raw !== 'object') return null\n  const state = raw as Record<string, unknown>\n  if (!isEmailStateStatus(state['status'])) return null\n  const atMs = Number(state['atMs'])\n  const source = state['source']\n  const enrollmentId = typeof state['enrollmentId'] === 'string' && state['enrollmentId'] ? state['enrollmentId'] : undefined\n  return {\n    status: state['status'],\n    atMs: Number.isFinite(atMs) && atMs > 0 ? atMs : 0,\n    source: (EMAIL_STATE_SOURCES as readonly unknown[]).includes(source) ? (source as EmailStateSource) : 'campaign',\n    detail: typeof state['detail'] === 'string' && state['detail'] ? state['detail'] : null,\n    ...(enrollmentId ? { enrollmentId } : {}),\n  }\n}\n\n/** Whether the state means the address must not be emailed by hand. */\nexport function emailStateForbidsEmail(state: EmailState | null | undefined): boolean {\n  return Boolean(state) && state?.status !== 'ok'\n}\n\n/**\n * The state a record holds after one more verdict: the incoming one when it\n * ranks at least as high as the current — a fresh bounce replaces an old\n * one, a block replaces a bounce, a member's mark replaces anything — else\n * the current. `force` writes the incoming state whatever stands, which is\n * how a release lands.\n */\nexport function nextEmailState(\n  current: EmailState | null | undefined,\n  incoming: EmailState,\n  options: { force?: boolean } = {},\n): EmailState {\n  if (!current || options.force) return incoming\n  return EMAIL_STATE_RANK[incoming.status] >= EMAIL_STATE_RANK[current.status] ? incoming : current\n}\n\n/** When the verdict was given, as the chip's tooltip and the refusal say it. */\nexport function emailStateWhen(state: Pick<EmailState, 'atMs'>): string {\n  if (!state.atMs) return ''\n  try {\n    return new Intl.DateTimeFormat('en-US', { dateStyle: 'medium' }).format(state.atMs)\n  } catch {\n    return new Date(state.atMs).toDateString()\n  }\n}\n\n/**\n * Why the record must not be emailed, in one sentence a disabled button or\n * a refused enrollment can show — or `null` when it may be.\n */\nexport function emailStateRefusal(state: EmailState | null | undefined): string | null {\n  if (!state || !emailStateForbidsEmail(state)) return null\n  const when = emailStateWhen(state)\n  const since = when ? ` on ${when}` : ''\n  const said = state.detail ? ` ${state.detail}` : ''\n  switch (state.status) {\n    case 'undeliverable':\n      return `Email to this address would bounce: its domain has no mail server${since ? ` (checked${since})` : ''}.${said}`\n    case 'bounced':\n      return `Email to this address bounced${since}: the mailbox does not exist.${said}`\n    case 'blocked':\n      return `Their mail gateway blocked email to this address${since}.${said}`\n    case 'unsubscribed':\n      return `They unsubscribed${since}.${said}`\n    case 'complained':\n      return `They marked an email as spam${since}.${said}`\n    case 'do_not_contact':\n      return `On the do-not-contact list${since}.${said}`\n    default:\n      return null\n  }\n}\n"],"names":["EMAIL_STATE_STATUSES","EMAIL_STATE_SOURCES","EMAIL_STATE_FIELD","EMAIL_STATE_LABELS","ok","undeliverable","bounced","blocked","unsubscribed","complained","do_not_contact","EMAIL_STATE_RANK","isEmailStateStatus","value","includes","readEmailState","record","raw","state","atMs","Number","source","enrollmentId","undefined","status","isFinite","detail","emailStateForbidsEmail","Boolean","nextEmailState","current","incoming","options","force","emailStateWhen","Intl","DateTimeFormat","dateStyle","format","Date","toDateString","emailStateRefusal","when","since","said"],"mappings":"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"}

package/src/lib/app-utils/forms.d.ts

@@ -179,6 +179,16 @@ export interface FormDocument<N = AglynNodeSchema> {
      * `false` on every create — see {@link newFormListFields}.
      */
     retired?: boolean;
+    /** The campaigns the form is filed under — see {@link formCampaignFields}. */
+    campaignIds?: string[];
+    /**
+     * Whether the form is in any campaign, as a boolean the Forms list can
+     * QUERY (AGL-3330): "in no campaign" is an empty array, and Firestore can
+     * neither find a document by an absent field nor ask an array for its
+     * length. Written beside `campaignIds` by every writer of it, through
+     * {@link formCampaignFields}.
+     */
+    inCampaign?: boolean;
     /** The Forms list's search fields — see {@link formListFields}. */
     nameLower?: string;
     nameTokens?: string[];
@@ -255,18 +265,45 @@ export declare function formListFields(form: {
     displayName?: unknown;
     slug?: unknown;
 }): FormListSearchFields;
+/**
+ * The campaign fields a form is written with, from the campaigns it is filed
+ * under (AGL-3330): the normalized ids, and `inCampaign`, the boolean the
+ * Forms list's "In a campaign" filter asks by equality.
+ *
+ * ⚠️ The ONE way to write a form's `campaignIds`. A writer that sets the ids
+ * without `inCampaign` leaves the form answering the filter by what it used
+ * to be filed under; `apps/console/specs/form-writers-use-the-helpers.spec.ts`
+ * refuses one. The campaign deletion pass removes an id with `arrayRemove`
+ * and restamps `inCampaign` from the form as it then stands.
+ */
+export declare function formCampaignFields(selected: unknown): {
+    campaignIds: string[];
+    inCampaign: boolean;
+};
+/**
+ * The `stats.leads` a form holds when nothing has been counted for it.
+ *
+ * A form that routes leads holds `0` until its first lead, so "Leads = 0"
+ * finds the lead surfaces that have produced nothing yet. A form that does
+ * not route leads holds `null`: it has no leads measurement, which is what
+ * "Leads is empty" asks. The recount and every writer of the switch agree
+ * through this and {@link formCountersFromSource}.
+ */
+export declare function formLeadsStatWhenUncounted(routesLeads: boolean): 0 | null;
 /**
  * What a NEW form is written with so the Forms list can query every filter
- * it offers (AGL-3330): its search fields, and an explicit value for each
+ * it offers (AGL-3330): its search keys, and an explicit value for each
  * field a query would otherwise have to find by its absence.
  *
  *  - `retired: false`, the queryable mirror of an unset `archivedAt`.
  *  - `routing.lead` as a boolean, `false` unless the form routes to leads, so
  *    "Lead routing is off" is an equality rather than a missing field.
- *  - `stats` with a NULL for each counter. Null, never zero: a form that has
- *    counted nothing has no figure, which is what the list's dash says, and a
- *    zero would claim a measurement. `/api/forms/submit` increments these,
- *    and an increment on null starts from nothing, so it needs no change.
+ *  - `inCampaign`, from the campaigns the form is created in.
+ *  - `stats` with a NULL for each counter, except `leads` on a form that
+ *    routes leads, which starts at `0` (see {@link formLeadsStatWhenUncounted}).
+ *    Null, never zero, where nothing is measured: a zero would claim a
+ *    measurement. `/api/forms/submit` increments these, and an increment on
+ *    null starts from nothing, so it needs no change.
  *
  * `routing` keeps whatever else it carries (a dataset binding).
  */
@@ -275,15 +312,66 @@ export declare function newFormListFields(form: {
     displayName?: unknown;
     slug?: unknown;
     routing?: FormRouting | null;
+    campaignIds?: unknown;
 }): FormListSearchFields & {
     retired: false;
     routing: FormRouting;
+    inCampaign: boolean;
     stats: {
         submissions: null;
-        leads: null;
+        leads: 0 | null;
         lastSubmissionAtMs: null;
     };
 };
+/** The source a lead filed by a form carries in `sources`. */
+export declare const FORM_LEAD_SOURCE_PREFIX = "form:";
+/** `form:{formId}` — the lead source a form's capture writes. */
+export declare function formLeadSource(formId: string): string;
+/** The form ids a lead's `sources` name, in order, deduplicated. */
+export declare function formIdsOfLeadSources(sources: unknown): string[];
+/** The three counters the Forms list filters by. */
+export interface FormCounterStats {
+    submissions: number | null;
+    leads: number | null;
+    lastSubmissionAtMs: number | null;
+}
+/** The counter fields, in reading order. */
+export declare const FORM_COUNTER_FIELDS: readonly (keyof FormCounterStats)[];
+/**
+ * The counters a form should hold, from the rows counted.
+ *
+ * Zero submissions is `null`, the list's "none yet", matching a new form.
+ * Leads follow {@link formLeadsStatWhenUncounted} when there are none — and
+ * a form that stopped routing leads keeps the leads it did file, because
+ * those people are still on the list.
+ */
+export declare function formCountersFromSource(source: {
+    submissions: number;
+    leads: number;
+    newestSubmissionAtMs: number | null;
+    routesLeads: boolean;
+}): FormCounterStats;
+/**
+ * How far the stored `lastSubmissionAtMs` may sit from the newest
+ * submission's `createdAt` and still agree.
+ *
+ * The submit path stamps the counter from its own clock after it has written
+ * the submission, whose `createdAt` is the server's commit time, and a lead
+ * capture runs between the two — so a counter that is right reads a little
+ * after the row. Ten minutes is far past that gap and far short of two
+ * submissions a merchant would tell apart.
+ */
+export declare const FORM_LAST_SUBMISSION_TOLERANCE_MS: number;
+/**
+ * The counters on which `stored` disagrees with `recounted`, in reading
+ * order; empty when the form holds what its rows say.
+ *
+ * An ABSENT counter disagrees with a `null` one: "is empty" asks
+ * `== null`, which a missing field does not answer.
+ */
+export declare function formCounterDrift(stored: Record<string, unknown> | null | undefined, recounted: FormCounterStats): (keyof FormCounterStats)[];
+/** The dotted-path update that puts `recounted` on a form. */
+export declare function formCounterPatch(recounted: FormCounterStats): Record<string, number | null>;
 /**
  * One entry in a form's `versions` subcollection.
  *
@@ -306,7 +394,10 @@ export interface FormVersion<N = AglynNodeSchema> {
  * bound and is the one the customer is billed on; a console surface that
  * counted it on render would be the expensive-read shape this product has
  * created repeatedly. `hosts/{hostId}/overlays/{overlayId}.stats` is the same
- * pattern with the same reasoning.
+ * pattern with the same reasoning. What an increment cannot see — a deleted
+ * submission, an erased lead, a failed write — is put back by the RECOUNT
+ * ({@link formCountersFromSource}), which runs after a removal and over every
+ * form from `tools/scripts/recount-form-stats.mjs`; never on render.
  */
 export interface FormStats {
     submissions?: number | null;
@@ -432,9 +523,10 @@ export declare function formPeriodKey(atMs: number | null | undefined): string |
  *
  * Every counter is `number | null` and the distinction is load-bearing. A
  * counter is `null` when nothing was recorded for it at all: `leads` is
- * incremented only by a form whose `routing.lead` is set, so a form that does
+ * counted only for a form whose `routing.lead` is set, so a form that does
  * not route leads has no leads measurement rather than a measured zero, and a
- * `0` in that slot states a result nobody took.
+ * `0` in that slot states a result nobody took. A form that routes leads and
+ * has filed none holds `0`, which is a measurement.
  */
 export interface FormStatsTotals {
     views: number | null;

package/src/lib/app-utils/forms.js

@@ -29,6 +29,7 @@
  * Everything that needs Firestore or `node:crypto` lives at the call sites.
  */ import { _ as _extends } from "@swc/helpers/_/_extends";
 import { FORMS_PLUGIN_ID } from "../plugin-manager/enabled-plugins.js";
+import { campaignMembershipValue } from "./campaign-membership.js";
 import { submissionMonthKey } from "./form-abuse-ceiling.js";
 import { displayNameSearchFields, nameSearchTokens } from "./name-search.js";
 /**
@@ -156,35 +157,164 @@ export const FORM_FIELD_COMPONENT_ID = 'formField';
         ]
     });
 }
+/**
+ * The campaign fields a form is written with, from the campaigns it is filed
+ * under (AGL-3330): the normalized ids, and `inCampaign`, the boolean the
+ * Forms list's "In a campaign" filter asks by equality.
+ *
+ * ⚠️ The ONE way to write a form's `campaignIds`. A writer that sets the ids
+ * without `inCampaign` leaves the form answering the filter by what it used
+ * to be filed under; `apps/console/specs/form-writers-use-the-helpers.spec.ts`
+ * refuses one. The campaign deletion pass removes an id with `arrayRemove`
+ * and restamps `inCampaign` from the form as it then stands.
+ */ export function formCampaignFields(selected) {
+    const campaignIds = campaignMembershipValue(Array.isArray(selected) ? selected : []);
+    return {
+        campaignIds,
+        inCampaign: campaignIds.length > 0
+    };
+}
+/**
+ * The `stats.leads` a form holds when nothing has been counted for it.
+ *
+ * A form that routes leads holds `0` until its first lead, so "Leads = 0"
+ * finds the lead surfaces that have produced nothing yet. A form that does
+ * not route leads holds `null`: it has no leads measurement, which is what
+ * "Leads is empty" asks. The recount and every writer of the switch agree
+ * through this and {@link formCountersFromSource}.
+ */ export function formLeadsStatWhenUncounted(routesLeads) {
+    return routesLeads ? 0 : null;
+}
 /**
  * What a NEW form is written with so the Forms list can query every filter
- * it offers (AGL-3330): its search fields, and an explicit value for each
+ * it offers (AGL-3330): its search keys, and an explicit value for each
  * field a query would otherwise have to find by its absence.
  *
  *  - `retired: false`, the queryable mirror of an unset `archivedAt`.
  *  - `routing.lead` as a boolean, `false` unless the form routes to leads, so
  *    "Lead routing is off" is an equality rather than a missing field.
- *  - `stats` with a NULL for each counter. Null, never zero: a form that has
- *    counted nothing has no figure, which is what the list's dash says, and a
- *    zero would claim a measurement. `/api/forms/submit` increments these,
- *    and an increment on null starts from nothing, so it needs no change.
+ *  - `inCampaign`, from the campaigns the form is created in.
+ *  - `stats` with a NULL for each counter, except `leads` on a form that
+ *    routes leads, which starts at `0` (see {@link formLeadsStatWhenUncounted}).
+ *    Null, never zero, where nothing is measured: a zero would claim a
+ *    measurement. `/api/forms/submit` increments these, and an increment on
+ *    null starts from nothing, so it needs no change.
  *
  * `routing` keeps whatever else it carries (a dataset binding).
  */ export function newFormListFields(form) {
     var _form_routing;
     var _form_routing1;
+    const routesLeads = ((_form_routing1 = form.routing) == null ? void 0 : _form_routing1.lead) === true;
     return _extends({}, formListFields(form), {
         retired: false,
         routing: _extends({}, (_form_routing = form.routing) != null ? _form_routing : {}, {
-            lead: ((_form_routing1 = form.routing) == null ? void 0 : _form_routing1.lead) === true
+            lead: routesLeads
         }),
+        inCampaign: formCampaignFields(form.campaignIds).inCampaign,
         stats: {
             submissions: null,
-            leads: null,
+            leads: formLeadsStatWhenUncounted(routesLeads),
             lastSubmissionAtMs: null
         }
     });
 }
+/*==========================================
+ * THE COUNTERS, RECOUNTED FROM WHAT THEY COUNT (AGL-3330).
+ *
+ * `stats.submissions`, `stats.leads` and `stats.lastSubmissionAtMs` are kept
+ * by increments on the submit path, which is cheap and never re-reads the
+ * collection it counts. An increment cannot see a delete, a failed write or
+ * a history written before it, so the stored figure drifts; the recount is
+ * what puts it back, from the rows themselves:
+ *
+ *  - submissions: the site's `formSubmissions` whose `formId` is the form;
+ *  - leads: the organization's leads whose `sources` name the form
+ *    (`form:{formId}`, {@link formLeadSource}) — PEOPLE this form brought in
+ *    that the workspace still holds, which is what the submit path counts
+ *    (a returning visitor, or a person already on the list through this
+ *    form, files no second lead);
+ *  - last submission: the newest of those submissions' `createdAt`.
+ *
+ * A server helper (`recountFormStats`) runs it after anything that removes a
+ * row, and `tools/scripts/recount-form-stats.mjs` runs it over every form.
+ * Both decide with the pure functions below; the script's twin answers
+ * `tools/scripts/lib/site-form-stats-recount.fixtures.json`, as this does.
+ *=========================================*/ /** The source a lead filed by a form carries in `sources`. */ export const FORM_LEAD_SOURCE_PREFIX = 'form:';
+/** `form:{formId}` — the lead source a form's capture writes. */ export function formLeadSource(formId) {
+    return `${FORM_LEAD_SOURCE_PREFIX}${formId}`;
+}
+/** The form ids a lead's `sources` name, in order, deduplicated. */ export function formIdsOfLeadSources(sources) {
+    if (!Array.isArray(sources)) return [];
+    const ids = [];
+    for (const source of sources){
+        if (typeof source !== 'string' || !source.startsWith(FORM_LEAD_SOURCE_PREFIX)) continue;
+        const id = source.slice(FORM_LEAD_SOURCE_PREFIX.length);
+        if (id && !ids.includes(id)) ids.push(id);
+    }
+    return ids;
+}
+/** The counter fields, in reading order. */ export const FORM_COUNTER_FIELDS = [
+    'submissions',
+    'leads',
+    'lastSubmissionAtMs'
+];
+/**
+ * The counters a form should hold, from the rows counted.
+ *
+ * Zero submissions is `null`, the list's "none yet", matching a new form.
+ * Leads follow {@link formLeadsStatWhenUncounted} when there are none — and
+ * a form that stopped routing leads keeps the leads it did file, because
+ * those people are still on the list.
+ */ export function formCountersFromSource(source) {
+    const submissions = source.submissions > 0 ? source.submissions : null;
+    return {
+        submissions,
+        leads: source.leads > 0 ? source.leads : formLeadsStatWhenUncounted(source.routesLeads),
+        lastSubmissionAtMs: submissions !== null && typeof source.newestSubmissionAtMs === 'number' ? source.newestSubmissionAtMs : null
+    };
+}
+/**
+ * How far the stored `lastSubmissionAtMs` may sit from the newest
+ * submission's `createdAt` and still agree.
+ *
+ * The submit path stamps the counter from its own clock after it has written
+ * the submission, whose `createdAt` is the server's commit time, and a lead
+ * capture runs between the two — so a counter that is right reads a little
+ * after the row. Ten minutes is far past that gap and far short of two
+ * submissions a merchant would tell apart.
+ */ export const FORM_LAST_SUBMISSION_TOLERANCE_MS = 10 * 60000;
+/** A stored counter as the recount compares it: a finite number, or `null`. */ function storedCounter(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+/**
+ * The counters on which `stored` disagrees with `recounted`, in reading
+ * order; empty when the form holds what its rows say.
+ *
+ * An ABSENT counter disagrees with a `null` one: "is empty" asks
+ * `== null`, which a missing field does not answer.
+ */ export function formCounterDrift(stored, recounted) {
+    const drift = [];
+    for (const field of FORM_COUNTER_FIELDS){
+        const raw = stored == null ? void 0 : stored[field];
+        const value = storedCounter(raw);
+        const want = recounted[field];
+        if (raw === undefined || value === null && raw !== null) {
+            drift.push(field);
+        } else if (field === 'lastSubmissionAtMs' && value !== null && want !== null) {
+            if (Math.abs(value - want) > FORM_LAST_SUBMISSION_TOLERANCE_MS) drift.push(field);
+        } else if (value !== want) {
+            drift.push(field);
+        }
+    }
+    return drift;
+}
+/** The dotted-path update that puts `recounted` on a form. */ export function formCounterPatch(recounted) {
+    return {
+        'stats.submissions': recounted.submissions,
+        'stats.leads': recounted.leads,
+        'stats.lastSubmissionAtMs': recounted.lastSubmissionAtMs
+    };
+}
 export const FORM_STAT_KINDS = [
     'views',
     'starts',