@aglyn/plugins-workflows 1.0.0-beta.179 → 1.0.0-beta.181

package/src/lib/engine/flow-enrollments.js

@@ -65,8 +65,10 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  */ import { personKey } from "@aglyn/aglyn/server";
 import { firebaseAdmin } from "@aglyn/tenant-data-admin";
 /**
- * `hosts/{hostId}/flowEnrollments/{actionId__personKey}` for an action, and
- * `{workflow-<workflowId>__personKey}` for a workflow.
+ * `hosts/{hostId}/flowEnrollments/{actionId__personKey}` for an action,
+ * `{workflow-<workflowId>__personKey}` for a workflow, and
+ * `{org-<automationId>__personKey}` for an org automation waiting on the site
+ * it ran on.
  */ export const FLOW_ENROLLMENTS_SUBCOLLECTION = 'flowEnrollments';
 /**
  * Documents one sweep may READ across every site.
@@ -105,9 +107,12 @@ import { firebaseAdmin } from "@aglyn/tenant-data-admin";
  * enrollments would key on something narrower than the person (the cart, the
  * order), which is a change to this function and to nothing else.
  */ export function flowEnrollmentId(actionId, key, automation) {
-    // A workflow's id is kept apart from an action's, so the two kinds can
-    // never share a row whatever ids their collections hand out.
-    return automation === 'workflow' ? `workflow-${actionId}__${key}` : `${actionId}__${key}`;
+    // Each kind's id is kept apart from the others', so no two kinds can ever
+    // share a row whatever ids their collections hand out — an org automation's
+    // id comes from a different collection than the site's own action ids.
+    if (automation === 'workflow') return `workflow-${actionId}__${key}`;
+    if (automation === 'org') return `org-${actionId}__${key}`;
+    return `${actionId}__${key}`;
 }
 function enrollmentsRef(hostId, firestore) {
     return (firestore != null ? firestore : firebaseAdmin.app().firestore()).collection('hosts').doc(hostId).collection(FLOW_ENROLLMENTS_SUBCOLLECTION);
@@ -156,8 +161,10 @@ function enrollmentsRef(hostId, firestore) {
         }
         const enrollment = _extends({
             hostId: options.hostId
-        }, options.automation === 'workflow' ? {
-            automation: 'workflow'
+        }, options.automation ? {
+            automation: options.automation
+        } : {}, options.automation === 'org' && options.orgId ? {
+            orgId: options.orgId
         } : {}, {
             actionId: options.actionId,
             actionName: String((_options_action_name = options.action.name) != null ? _options_action_name : ''),

package/src/lib/engine/flow-enrollments.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/workflows/src/lib/engine/flow-enrollments.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 * WHERE A PERSON WAITS, between one step of a flow and the next.\n *\n * An action used to be trigger → immediate steps, start to finish inside the\n * request that emitted the event. A `wait` step ends that: the run stops, and\n * something else has to pick it up minutes or weeks later. This module is the\n * something else's memory.\n *\n * ## The scheduling model, and why it survives a deploy\n *\n * There is no timer anywhere. A wait is a ROW — `resumeAtMs` on a document in\n * `hosts/{hostId}/flowEnrollments` — and the resume is a query for rows whose\n * time has come, run by the platform job beat that already exists. Nothing is\n * held in a process, so nothing is lost when the process ends: a deploy, a\n * restart, a cold start and a region failover all leave the row exactly where\n * it was, and the next beat finds it. The two worked examples in this repo\n * take the same shape for the same reason — `campaign-process-scheduled.ts`\n * claims `status: 'scheduled'` campaigns whose `sendAtMs` has passed, and the\n * abandoned-checkout scan re-reads any checkout it did not stamp.\n *\n * A beat that dies mid-resume is the case worth stating. The claim below flips\n * `waiting` → `running` in a transaction, so a second beat cannot pick up the\n * same enrollment; and a `running` row whose beat never came back is re-armed\n * by {@link FLOW_CLAIM_STALE_MS}, which is the difference between \"somebody is\n * working on this\" and \"somebody died holding this\".\n *\n * ## What it costs, which is not \"every enrollment on every beat\"\n *\n * The sweep reads DUE rows and only due rows: the query carries\n * `resumeAtMs <= now`, so a site with ten thousand people waiting three days\n * costs nothing on the beats before those three days are up. That is the whole\n * difference between this and the naive design, which re-reads every enrolled\n * person on every beat to ask whether their time has come.\n *\n * On top of that, {@link FLOW_RESUME_SCAN_BUDGET} bounds one beat's work and a\n * cursor resumes it — the shape `dynamic-list-materialize.ts` uses. The budget\n * matters even though the query is already narrow, because a due row that\n * cannot be acted on (a locked host) stays due: without paging past it, one\n * wall of locked rows at the head of the queue would starve every enrollment\n * behind it for as long as the lock lasted.\n *\n * ## ⛔ A BUDGET NEVER DROPS AN ENROLLMENT\n *\n * Running out of budget stops the sweep where it is. It never marks an\n * enrollment done, never advances its step, and never deletes it — the row\n * stays `waiting` and overdue, and the next beat starts again from the front\n * of the queue, which is where the oldest overdue work is. The same rule the\n * list materializer states: a bound on WORK is not a bound on PEOPLE.\n */\n\nimport { personKey } from '@aglyn/aglyn/server'\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport type { PluginJobHostGate } from '@aglyn/aglyn/server'\nimport type { WorkflowStep } from './workflow-steps'\n\n/**\n * `hosts/{hostId}/flowEnrollments/{actionId__personKey}` for an action, and\n * `{workflow-<workflowId>__personKey}` for a workflow.\n */\nexport const FLOW_ENROLLMENTS_SUBCOLLECTION = 'flowEnrollments'\n\n/**\n * Documents one sweep may READ across every site.\n *\n * A bound on work, not on membership — see the note above. Sized well past a\n * normal beat's due queue so the ordinary case never pages at all, and far\n * short of what one API invocation should spend.\n */\nexport const FLOW_RESUME_SCAN_BUDGET = 500\n\n/** Due enrollments read per page. */\nconst PAGE_SIZE = 50\n\n/**\n * How long a claim may go unfinished before another beat may take it.\n *\n * A `running` row is one a beat is part-way through. If that beat's process\n * ends — a deploy mid-resume, a function timeout, an unhandled throw that\n * escaped the isolation — nothing ever clears the flag, and without this the\n * enrollment would be stranded `running` for ever: not waiting, so no sweep\n * finds it; not done, so nobody is told.\n *\n * Ten minutes is far longer than a resume takes (a handful of Firestore reads\n * and at most one email) and far shorter than the shortest wait anybody\n * authors, so the only thing it can re-arm is a claim nobody is holding.\n *\n * The cost of getting it wrong is a step running twice, which is why the\n * window is generous rather than tight.\n */\nexport const FLOW_CLAIM_STALE_MS = 10 * 60_000\n\nexport type FlowEnrollmentStatus = 'waiting' | 'running'\n\n/**\n * Why an enrollment ended. Recorded on the run history, never on the\n * enrollment — the row is deleted when the flow ends, so the activity\n * collection is where \"what happened to this person\" lives.\n */\nexport type FlowEnrollmentEnding =\n  /** Every remaining step ran. */\n  | 'completed'\n  /** An `exitFlow` step, or a guard that ended the run. */\n  | 'exited'\n  /** The action was deleted, disabled, or lost its entitlement. */\n  | 'flow-stopped'\n\nexport interface FlowEnrollment {\n  hostId: string\n  /**\n   * What is waiting: `workflow` for a workflow's run, absent for an action's\n   * — which is every enrollment written before a workflow could wait, so an\n   * absent field is read as an action for as long as those rows exist.\n   */\n  automation?: 'workflow'\n  /** The automation's document id: the action's, or the workflow's. */\n  actionId: string\n  actionName: string\n  status: FlowEnrollmentStatus\n  /** When this flow continues. ALWAYS set — the sweep orders on it. */\n  resumeAtMs: number\n  /** Index into {@link steps} of the step that runs on resume. */\n  nextStepIndex: number\n  /**\n   * THE FLOW AS IT WAS WHEN THIS PERSON ENTERED IT.\n   *\n   * Not a reference to the action's current steps, and this is the whole\n   * answer to \"what happens to a flow somebody is already waiting inside\".\n   * `nextStepIndex` is a position in a LIST, and an author who reorders,\n   * inserts or deletes a step moves every position after it — so resuming a\n   * three-day wait against the edited list would deliver whatever now happens\n   * to sit at index 4. That is not a changed flow, it is a scrambled one, and\n   * the person it happens to is the one who cannot see it.\n   *\n   * So an edit applies to everyone who enrolls AFTER it, and nobody who is\n   * already inside. The trade is that a merchant who fixes a typo in step 3\n   * does not fix it for the people mid-wait; the alternative trade is sending\n   * them a step from a different flow, which is worse and silent.\n   *\n   * Bounded by `ACTION_MAX_STEPS` for an action, so the snapshot is ten\n   * small objects, and by `WORKFLOW_MAX_STEPS` for a workflow, whose snapshot\n   * holds its function calls beside its Actions steps.\n   */\n  steps: WorkflowStep[]\n  /** The event a `waitForEvent` is watching for; absent for a plain wait. */\n  awaitingEvent?: string | null\n  /** `sha256` of the person's address — the wake lookup key. */\n  personKey: string\n  email: string\n  /** The trigger payload, carried forward so later steps see the same scope. */\n  payload: Record<string, unknown>\n  /** The event that started the flow, for the run-history line. */\n  event: string\n  enrolledAtMs: number\n  updatedAtMs: number\n  /** How many times this enrollment has been picked up. */\n  resumes: number\n  /** Set while `running`; how {@link FLOW_CLAIM_STALE_MS} is measured. */\n  claimedAtMs?: number\n}\n\n/**\n * ONE LIVE ENROLLMENT PER PERSON PER FLOW, by construction.\n *\n * The document id is derived rather than generated, so a second concurrent\n * enrollment is not a race to detect — it is a write to a document that\n * already exists. A shopper who abandons three carts in an hour gets one\n * recovery sequence, not three overlapping ones, and the guarantee holds\n * across processes because it is Firestore's and not a lock of ours.\n *\n * DELIBERATE, and reversible: a flow that genuinely wants concurrent\n * enrollments would key on something narrower than the person (the cart, the\n * order), which is a change to this function and to nothing else.\n */\nexport function flowEnrollmentId(\n  actionId: string,\n  key: string,\n  automation?: 'workflow',\n): string {\n  // A workflow's id is kept apart from an action's, so the two kinds can\n  // never share a row whatever ids their collections hand out.\n  return automation === 'workflow'\n    ? `workflow-${actionId}__${key}`\n    : `${actionId}__${key}`\n}\n\nfunction enrollmentsRef(\n  hostId: string,\n  firestore?: any,\n): FirebaseFirestore.CollectionReference {\n  return (firestore ?? firebaseAdmin.app().firestore())\n    .collection('hosts')\n    .doc(hostId)\n    .collection(FLOW_ENROLLMENTS_SUBCOLLECTION)\n}\n\nexport interface EnrollInFlowOptions {\n  hostId: string\n  /** `workflow` for a workflow's run; absent for an action's. */\n  automation?: 'workflow'\n  /** The automation's document id. */\n  actionId: string\n  action: { name?: string; steps?: readonly WorkflowStep[] }\n  /** The address the flow is about. A flow with no person cannot wait. */\n  email: string\n  event: string\n  payload: Record<string, unknown>\n  /** Index of the step that runs when the wait ends. */\n  nextStepIndex: number\n  resumeAtMs: number\n  awaitingEvent?: string | null\n  nowMs?: number\n  firestore?: any\n}\n\nexport type EnrollInFlowResult =\n  | { enrolled: true; id: string }\n  | { enrolled: false; reason: 'no-person' | 'already-waiting' }\n\n/**\n * Suspends a run, durably.\n *\n * Refuses rather than improvises when there is nobody to wait for. A flow\n * that waits is a flow that continues later for a PERSON — it is how the\n * enrollment is keyed, how a `waitForEvent` is woken, and who the next step's\n * email is addressed to. An anonymous wait would have no dedupe key, so a\n * page-view trigger on a busy site would mint an enrollment per visit; and\n * nothing downstream could use it. Saying so is better than silently\n * enrolling nobody.\n */\nexport async function enrollInFlow(\n  options: EnrollInFlowOptions,\n): Promise<EnrollInFlowResult> {\n  const key = personKey(options.email)\n  if (!key) return { enrolled: false, reason: 'no-person' }\n  const nowMs = options.nowMs ?? Date.now()\n  const ref = enrollmentsRef(options.hostId, options.firestore).doc(\n    flowEnrollmentId(options.actionId, key, options.automation),\n  )\n  const firestore = options.firestore ?? firebaseAdmin.app().firestore()\n  return await firestore.runTransaction(\n    async (transaction: FirebaseFirestore.Transaction) => {\n      const existing = await transaction.get(ref)\n      /*\n       * A row that is `waiting` or freshly `running` belongs to a live\n       * enrollment and this one is a duplicate. A STALE `running` row is a\n       * claim nobody is holding (see FLOW_CLAIM_STALE_MS) and a completed\n       * flow deletes its row, so anything else is free to be overwritten —\n       * which is what lets the same person go through the same welcome series\n       * again next year.\n       */\n      if (existing.exists) {\n        const status = existing.get('status')\n        const claimedAtMs = Number(existing.get('claimedAtMs') ?? 0)\n        const live =\n          status === 'waiting' ||\n          (status === 'running' && nowMs - claimedAtMs < FLOW_CLAIM_STALE_MS)\n        if (live) {\n          return { enrolled: false, reason: 'already-waiting' as const }\n        }\n      }\n      const enrollment: FlowEnrollment = {\n        hostId: options.hostId,\n        ...(options.automation === 'workflow'\n          ? { automation: 'workflow' as const }\n          : {}),\n        actionId: options.actionId,\n        actionName: String(options.action.name ?? ''),\n        status: 'waiting',\n        resumeAtMs: options.resumeAtMs,\n        nextStepIndex: options.nextStepIndex,\n        steps: [...(options.action.steps ?? [])],\n        personKey: key,\n        email: String(options.email).trim().toLowerCase(),\n        payload: options.payload ?? {},\n        event: options.event,\n        enrolledAtMs: nowMs,\n        updatedAtMs: nowMs,\n        resumes: 0,\n        ...(options.awaitingEvent\n          ? { awaitingEvent: options.awaitingEvent }\n          : { awaitingEvent: null }),\n      }\n      // `set`, not `create`: the transaction above has already decided this id\n      // is free, and a completed flow's deleted row may be re-enrolled.\n      transaction.set(ref, enrollment)\n      return { enrolled: true as const, id: ref.id }\n    },\n  )\n}\n\n/**\n * Takes an enrollment out of the queue for this beat, or answers null.\n *\n * The claim and the read are one transaction, so two beats — an overlapping\n * schedule, a retried invocation, two regions — cannot both resume the same\n * person. `campaign-process-scheduled.ts` claims a due campaign exactly this\n * way and for exactly this reason.\n */\nexport async function claimFlowEnrollment(\n  ref: FirebaseFirestore.DocumentReference,\n  options?: { nowMs?: number; firestore?: any },\n): Promise<FlowEnrollment | null> {\n  const nowMs = options?.nowMs ?? Date.now()\n  const firestore =\n    options?.firestore ?? ref.firestore ?? firebaseAdmin.app().firestore()\n  return await firestore.runTransaction(\n    async (transaction: FirebaseFirestore.Transaction) => {\n      const fresh = await transaction.get(ref)\n      if (!fresh.exists) return null\n      const status = fresh.get('status')\n      const claimedAtMs = Number(fresh.get('claimedAtMs') ?? 0)\n      const claimable =\n        status === 'waiting' ||\n        (status === 'running' && nowMs - claimedAtMs >= FLOW_CLAIM_STALE_MS)\n      if (!claimable) return null\n      transaction.update(ref, {\n        status: 'running',\n        claimedAtMs: nowMs,\n        updatedAtMs: nowMs,\n      })\n      return { ...(fresh.data() as FlowEnrollment), status: 'running' }\n    },\n  )\n}\n\n/**\n * Puts a claimed enrollment back without having run it.\n *\n * SKIPPED, NOT DROPPED. Used when the resume cannot proceed for a reason a\n * later beat may pass — the platform's hourly send ceiling had no room, the\n * recipient's own frequency window is full — so the step is attempted again\n * rather than lost. `retryAtMs` pushes the row down the queue so it does not\n * spin on the same refusal every minute.\n */\nexport async function deferFlowEnrollment(\n  ref: FirebaseFirestore.DocumentReference,\n  retryAtMs: number,\n  nowMs = Date.now(),\n): Promise<void> {\n  await ref\n    .set(\n      {\n        status: 'waiting',\n        resumeAtMs: retryAtMs,\n        claimedAtMs: null,\n        updatedAtMs: nowMs,\n      },\n      { merge: true },\n    )\n    .catch(() => undefined)\n}\n\n/** Advances a claimed enrollment to the next wait, keeping it in the queue. */\nexport async function advanceFlowEnrollment(\n  ref: FirebaseFirestore.DocumentReference,\n  update: {\n    nextStepIndex: number\n    resumeAtMs: number\n    awaitingEvent?: string | null\n    payload?: Record<string, unknown>\n  },\n  nowMs = Date.now(),\n): Promise<void> {\n  await ref\n    .set(\n      {\n        status: 'waiting',\n        claimedAtMs: null,\n        updatedAtMs: nowMs,\n        resumes: firebaseAdmin.firestore.FieldValue.increment(1),\n        nextStepIndex: update.nextStepIndex,\n        resumeAtMs: update.resumeAtMs,\n        awaitingEvent: update.awaitingEvent ?? null,\n        ...(update.payload ? { payload: update.payload } : {}),\n      },\n      { merge: true },\n    )\n    .catch(() => undefined)\n}\n\n/**\n * Ends an enrollment by DELETING it.\n *\n * The row is live state, not a record. What happened to this person is\n * already written to `hosts/{hostId}/activity` — the same run history every\n * immediate action writes — so keeping a `done` row would be a second,\n * shorter answer to a question that is already answered, growing for ever in\n * a collection the sweep has to index.\n *\n * Deleting is also what lets the same person enter the same flow again: the\n * id is derived from the person, so a tombstone would be a permanent refusal\n * to ever run this sequence for them a second time.\n */\nexport async function endFlowEnrollment(\n  ref: FirebaseFirestore.DocumentReference,\n): Promise<void> {\n  await ref.delete().catch(() => undefined)\n}\n\n/**\n * The enrollments this person's event should wake, on this site.\n *\n * Keyed, bounded and cheap: three equality filters and a small limit, which\n * Firestore serves by merging single-field indexes. This is what keeps\n * `waitForEvent` off a polling design — nothing scans the enrolled population\n * looking for a match, the event arrives already knowing who it is about.\n *\n * The CALLER decides whether to ask at all. `runEventActions` fires on every\n * page view of every published site, so asking on every event would be a\n * query per visitor; it asks only when the payload names a person, which a\n * page view does not.\n */\nexport async function findFlowEnrollmentsAwaiting(options: {\n  hostId: string\n  event: string\n  email: string\n  firestore?: any\n  limit?: number\n}): Promise<FirebaseFirestore.QueryDocumentSnapshot[]> {\n  const key = personKey(options.email)\n  const event = String(options.event ?? '').trim()\n  if (!key || !event || !options.hostId) return []\n  try {\n    const snapshot = await enrollmentsRef(options.hostId, options.firestore)\n      .where('awaitingEvent', '==', event)\n      .where('personKey', '==', key)\n      .where('status', '==', 'waiting')\n      .limit(options.limit ?? 5)\n      .get()\n    return snapshot.docs\n  } catch (error) {\n    console.error('[flow] awaiting-event lookup failed', options.hostId, error)\n    return []\n  }\n}\n\n/** Where a partial sweep stopped, so the next beat resumes rather than restarts. */\nexport interface FlowSweepCursor {\n  /** Full document path of the last enrollment read. */\n  path: string\n}\n\nexport interface FlowSweepResult {\n  /** Due enrollments read, against the budget. */\n  scanned: number\n  /** Enrollments this beat claimed and ran. */\n  resumed: number\n  /** Rows left untouched because their site is locked. */\n  skippedLocked: number\n  /** Rows another beat already held. */\n  skippedClaimed: number\n  /** False when the scan budget ran out — `cursor` says where to resume. */\n  complete: boolean\n  cursor: FlowSweepCursor | null\n}\n\n/**\n * One pass over the flows whose wait has ended.\n *\n * The RESUME itself is injected. Running a step needs the action executor,\n * which needs entitlements, datasets, webhooks and the mail path; keeping it\n * out of this function is what lets the scheduling contract — due-ness, the\n * claim, the budget, the lock — be exercised without any of that.\n */\nexport async function sweepDueFlowEnrollments(\n  gate: PluginJobHostGate,\n  options: {\n    resume: (\n      enrollment: FlowEnrollment,\n      ref: FirebaseFirestore.DocumentReference,\n    ) => Promise<void>\n    nowMs?: number\n    scanBudget?: number\n    cursor?: FlowSweepCursor | null\n    firestore?: any\n  },\n): Promise<FlowSweepResult> {\n  const firestore = options.firestore ?? firebaseAdmin.app().firestore()\n  const nowMs = options.nowMs ?? Date.now()\n  const budget = options.scanBudget ?? FLOW_RESUME_SCAN_BUDGET\n  const result: FlowSweepResult = {\n    scanned: 0,\n    resumed: 0,\n    skippedLocked: 0,\n    skippedClaimed: 0,\n    complete: true,\n    cursor: null,\n  }\n  let after: FirebaseFirestore.DocumentSnapshot | null = options.cursor?.path\n    ? await firestore\n        .doc(options.cursor.path)\n        .get()\n        .catch(() => null)\n    : null\n\n  for (;;) {\n    /*\n     * Ordered by `resumeAtMs`, which every writer in this module sets on\n     * every write. That is load-bearing twice over: an `orderBy` on a field\n     * DROPS documents that lack it, so a writer that ever omitted it would\n     * make those enrollments invisible to the only thing that resumes them;\n     * and ordering oldest-due-first is what makes a budget fair, because the\n     * work a short beat leaves behind is the newest rather than whichever\n     * rows Firestore happened to return.\n     */\n    /*\n     * The page is capped by what is LEFT of the budget, not only by\n     * `PAGE_SIZE`. Checking the budget between pages would let a run whose\n     * budget is smaller than one page read the whole page first — the budget\n     * would then describe how much was reported rather than how much was\n     * read, which is the opposite of what a read budget is for.\n     */\n    const remaining = budget - result.scanned\n    if (remaining <= 0) break\n    let query = firestore\n      .collectionGroup(FLOW_ENROLLMENTS_SUBCOLLECTION)\n      .where('status', '==', 'waiting')\n      .where('resumeAtMs', '<=', nowMs)\n      .orderBy('resumeAtMs')\n      .limit(Math.min(PAGE_SIZE, remaining))\n    if (after) query = query.startAfter(after)\n    const page = await query.get()\n    if (page.empty) break\n\n    for (const doc of page.docs) {\n      result.scanned += 1\n      after = doc\n      const hostId =\n        String(doc.get('hostId') ?? '') || (doc.ref.parent.parent?.id ?? '')\n      if (!hostId) continue\n      /*\n       * LOCKDOWN, first in the loop body and before any write. `continue`\n       * leaves the row `waiting` and overdue, so the flow resumes on the\n       * first beat after the lift rather than being cancelled by a pause.\n       */\n      if (await gate.isLocked(hostId)) {\n        result.skippedLocked += 1\n        continue\n      }\n      const enrollment = await claimFlowEnrollment(doc.ref, { nowMs })\n      if (!enrollment) {\n        result.skippedClaimed += 1\n        continue\n      }\n      try {\n        await options.resume(enrollment, doc.ref)\n        result.resumed += 1\n      } catch (error) {\n        /*\n         * One broken flow must not stop the sweep — the same isolation the\n         * dynamic-list sweep gives each list. The claim is released so a\n         * later beat retries; a permanently broken step therefore retries for\n         * as long as the enrollment lives, which is bounded by its own wait\n         * ceiling and is the recoverable direction.\n         */\n        console.error('[flow] resume failed', doc.ref.path, error)\n        await deferFlowEnrollment(doc.ref, nowMs + FLOW_CLAIM_STALE_MS, nowMs)\n      }\n    }\n\n    if (result.scanned >= budget) {\n      result.complete = false\n      result.cursor = after ? { path: after.ref.path } : null\n      return result\n    }\n    if (page.size < Math.min(PAGE_SIZE, remaining)) break\n  }\n  return result\n}\n"],"names":["personKey","firebaseAdmin","FLOW_ENROLLMENTS_SUBCOLLECTION","FLOW_RESUME_SCAN_BUDGET","PAGE_SIZE","FLOW_CLAIM_STALE_MS","flowEnrollmentId","actionId","key","automation","enrollmentsRef","hostId","firestore","app","collection","doc","enrollInFlow","options","email","enrolled","reason","nowMs","Date","now","ref","runTransaction","transaction","existing","get","exists","status","claimedAtMs","Number","live","enrollment","actionName","String","action","name","resumeAtMs","nextStepIndex","steps","trim","toLowerCase","payload","event","enrolledAtMs","updatedAtMs","resumes","awaitingEvent","set","id","claimFlowEnrollment","fresh","claimable","update","data","deferFlowEnrollment","retryAtMs","merge","catch","undefined","advanceFlowEnrollment","FieldValue","increment","endFlowEnrollment","delete","findFlowEnrollmentsAwaiting","snapshot","where","limit","docs","error","console","sweepDueFlowEnrollments","gate","budget","scanBudget","result","scanned","resumed","skippedLocked","skippedClaimed","complete","cursor","after","path","remaining","query","collectionGroup","orderBy","Math","min","startAfter","page","empty","parent","isLocked","resume","size"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgDC,GAED,SAASA,SAAS,QAAQ,sBAAqB;AAC/C,SAASC,aAAa,QAAQ,2BAA0B;AAIxD;;;CAGC,GACD,OAAO,MAAMC,iCAAiC,kBAAiB;AAE/D;;;;;;CAMC,GACD,OAAO,MAAMC,0BAA0B,IAAG;AAE1C,mCAAmC,GACnC,MAAMC,YAAY;AAElB;;;;;;;;;;;;;;;CAeC,GACD,OAAO,MAAMC,sBAAsB,KAAK,MAAM;AAuE9C;;;;;;;;;;;;CAYC,GACD,OAAO,SAASC,iBACdC,QAAgB,EAChBC,GAAW,EACXC,UAAuB;IAEvB,uEAAuE;IACvE,6DAA6D;IAC7D,OAAOA,eAAe,aAClB,CAAC,SAAS,EAAEF,SAAS,EAAE,EAAEC,KAAK,GAC9B,GAAGD,SAAS,EAAE,EAAEC,KAAK;AAC3B;AAEA,SAASE,eACPC,MAAc,EACdC,SAAe;IAEf,OAAO,CAACA,oBAAAA,YAAaX,cAAcY,GAAG,GAAGD,SAAS,IAC/CE,UAAU,CAAC,SACXC,GAAG,CAACJ,QACJG,UAAU,CAACZ;AAChB;AAyBA;;;;;;;;;;CAUC,GACD,OAAO,eAAec,aACpBC,OAA4B;QAIdA,gBAIIA;IANlB,MAAMT,MAAMR,UAAUiB,QAAQC,KAAK;IACnC,IAAI,CAACV,KAAK,OAAO;QAAEW,UAAU;QAAOC,QAAQ;IAAY;IACxD,MAAMC,SAAQJ,iBAAAA,QAAQI,KAAK,YAAbJ,iBAAiBK,KAAKC,GAAG;IACvC,MAAMC,MAAMd,eAAeO,QAAQN,MAAM,EAAEM,QAAQL,SAAS,EAAEG,GAAG,CAC/DT,iBAAiBW,QAAQV,QAAQ,EAAEC,KAAKS,QAAQR,UAAU;IAE5D,MAAMG,aAAYK,qBAAAA,QAAQL,SAAS,YAAjBK,qBAAqBhB,cAAcY,GAAG,GAAGD,SAAS;IACpE,OAAO,MAAMA,UAAUa,cAAc,CACnC,OAAOC;YA0BgBT,sBAIPA,uBAGHA;QAhCX,MAAMU,WAAW,MAAMD,YAAYE,GAAG,CAACJ;QACvC;;;;;;;OAOC,GACD,IAAIG,SAASE,MAAM,EAAE;gBAEQF;YAD3B,MAAMG,SAASH,SAASC,GAAG,CAAC;YAC5B,MAAMG,cAAcC,QAAOL,gBAAAA,SAASC,GAAG,CAAC,0BAAbD,gBAA+B;YAC1D,MAAMM,OACJH,WAAW,aACVA,WAAW,aAAaT,QAAQU,cAAc1B;YACjD,IAAI4B,MAAM;gBACR,OAAO;oBAAEd,UAAU;oBAAOC,QAAQ;gBAA2B;YAC/D;QACF;QACA,MAAMc,aAA6B;YACjCvB,QAAQM,QAAQN,MAAM;WAClBM,QAAQR,UAAU,KAAK,aACvB;YAAEA,YAAY;QAAoB,IAClC,CAAC;YACLF,UAAUU,QAAQV,QAAQ;YAC1B4B,YAAYC,QAAOnB,uBAAAA,QAAQoB,MAAM,CAACC,IAAI,YAAnBrB,uBAAuB;YAC1Ca,QAAQ;YACRS,YAAYtB,QAAQsB,UAAU;YAC9BC,eAAevB,QAAQuB,aAAa;YACpCC,OAAO;oBAAKxB,wBAAAA,QAAQoB,MAAM,CAACI,KAAK,YAApBxB,wBAAwB,EAAE;aAAE;YACxCjB,WAAWQ;YACXU,OAAOkB,OAAOnB,QAAQC,KAAK,EAAEwB,IAAI,GAAGC,WAAW;YAC/CC,OAAO,GAAE3B,mBAAAA,QAAQ2B,OAAO,YAAf3B,mBAAmB,CAAC;YAC7B4B,OAAO5B,QAAQ4B,KAAK;YACpBC,cAAczB;YACd0B,aAAa1B;YACb2B,SAAS;WACL/B,QAAQgC,aAAa,GACrB;YAAEA,eAAehC,QAAQgC,aAAa;QAAC,IACvC;YAAEA,eAAe;QAAK;QAE5B,yEAAyE;QACzE,kEAAkE;QAClEvB,YAAYwB,GAAG,CAAC1B,KAAKU;QACrB,OAAO;YAAEf,UAAU;YAAegC,IAAI3B,IAAI2B,EAAE;QAAC;IAC/C;AAEJ;AAEA;;;;;;;CAOC,GACD,OAAO,eAAeC,oBACpB5B,GAAwC,EACxCP,OAA6C;cAI3CA;IAFF,MAAMI,gBAAQJ,2BAAAA,QAASI,KAAK,mBAAIC,KAAKC,GAAG;IACxC,MAAMX,aACJK,iBAAAA,2BAAAA,QAASL,SAAS,oBAAIY,IAAIZ,SAAS,YAAnCK,QAAuChB,cAAcY,GAAG,GAAGD,SAAS;IACtE,OAAO,MAAMA,UAAUa,cAAc,CACnC,OAAOC;YAIsB2B;QAH3B,MAAMA,QAAQ,MAAM3B,YAAYE,GAAG,CAACJ;QACpC,IAAI,CAAC6B,MAAMxB,MAAM,EAAE,OAAO;QAC1B,MAAMC,SAASuB,MAAMzB,GAAG,CAAC;QACzB,MAAMG,cAAcC,QAAOqB,aAAAA,MAAMzB,GAAG,CAAC,0BAAVyB,aAA4B;QACvD,MAAMC,YACJxB,WAAW,aACVA,WAAW,aAAaT,QAAQU,eAAe1B;QAClD,IAAI,CAACiD,WAAW,OAAO;QACvB5B,YAAY6B,MAAM,CAAC/B,KAAK;YACtBM,QAAQ;YACRC,aAAaV;YACb0B,aAAa1B;QACf;QACA,OAAO,aAAMgC,MAAMG,IAAI;YAAuB1B,QAAQ;;IACxD;AAEJ;AAEA;;;;;;;;CAQC,GACD,OAAO,eAAe2B,oBACpBjC,GAAwC,EACxCkC,SAAiB,EACjBrC,QAAQC,KAAKC,GAAG,EAAE;IAElB,MAAMC,IACH0B,GAAG,CACF;QACEpB,QAAQ;QACRS,YAAYmB;QACZ3B,aAAa;QACbgB,aAAa1B;IACf,GACA;QAAEsC,OAAO;IAAK,GAEfC,KAAK,CAAC,IAAMC;AACjB;AAEA,6EAA6E,GAC7E,OAAO,eAAeC,sBACpBtC,GAAwC,EACxC+B,MAKC,EACDlC,QAAQC,KAAKC,GAAG,EAAE;QAWGgC;IATrB,MAAM/B,IACH0B,GAAG,CACF;QACEpB,QAAQ;QACRC,aAAa;QACbgB,aAAa1B;QACb2B,SAAS/C,cAAcW,SAAS,CAACmD,UAAU,CAACC,SAAS,CAAC;QACtDxB,eAAee,OAAOf,aAAa;QACnCD,YAAYgB,OAAOhB,UAAU;QAC7BU,aAAa,GAAEM,wBAAAA,OAAON,aAAa,YAApBM,wBAAwB;OACnCA,OAAOX,OAAO,GAAG;QAAEA,SAASW,OAAOX,OAAO;IAAC,IAAI,CAAC,IAEtD;QAAEe,OAAO;IAAK,GAEfC,KAAK,CAAC,IAAMC;AACjB;AAEA;;;;;;;;;;;;CAYC,GACD,OAAO,eAAeI,kBACpBzC,GAAwC;IAExC,MAAMA,IAAI0C,MAAM,GAAGN,KAAK,CAAC,IAAMC;AACjC;AAEA;;;;;;;;;;;;CAYC,GACD,OAAO,eAAeM,4BAA4BlD,OAMjD;QAEsBA;IADrB,MAAMT,MAAMR,UAAUiB,QAAQC,KAAK;IACnC,MAAM2B,QAAQT,QAAOnB,iBAAAA,QAAQ4B,KAAK,YAAb5B,iBAAiB,IAAIyB,IAAI;IAC9C,IAAI,CAAClC,OAAO,CAACqC,SAAS,CAAC5B,QAAQN,MAAM,EAAE,OAAO,EAAE;IAChD,IAAI;YAKOM;QAJT,MAAMmD,WAAW,MAAM1D,eAAeO,QAAQN,MAAM,EAAEM,QAAQL,SAAS,EACpEyD,KAAK,CAAC,iBAAiB,MAAMxB,OAC7BwB,KAAK,CAAC,aAAa,MAAM7D,KACzB6D,KAAK,CAAC,UAAU,MAAM,WACtBC,KAAK,EAACrD,iBAAAA,QAAQqD,KAAK,YAAbrD,iBAAiB,GACvBW,GAAG;QACN,OAAOwC,SAASG,IAAI;IACtB,EAAE,OAAOC,OAAO;QACdC,QAAQD,KAAK,CAAC,uCAAuCvD,QAAQN,MAAM,EAAE6D;QACrE,OAAO,EAAE;IACX;AACF;AAsBA;;;;;;;CAOC,GACD,OAAO,eAAeE,wBACpBC,IAAuB,EACvB1D,OASC;QAEiBA,oBACJA,gBACCA;QASwCA;IAXvD,MAAML,aAAYK,qBAAAA,QAAQL,SAAS,YAAjBK,qBAAqBhB,cAAcY,GAAG,GAAGD,SAAS;IACpE,MAAMS,SAAQJ,iBAAAA,QAAQI,KAAK,YAAbJ,iBAAiBK,KAAKC,GAAG;IACvC,MAAMqD,UAAS3D,sBAAAA,QAAQ4D,UAAU,YAAlB5D,sBAAsBd;IACrC,MAAM2E,SAA0B;QAC9BC,SAAS;QACTC,SAAS;QACTC,eAAe;QACfC,gBAAgB;QAChBC,UAAU;QACVC,QAAQ;IACV;IACA,IAAIC,QAAmDpE,EAAAA,kBAAAA,QAAQmE,MAAM,qBAAdnE,gBAAgBqE,IAAI,IACvE,MAAM1E,UACHG,GAAG,CAACE,QAAQmE,MAAM,CAACE,IAAI,EACvB1D,GAAG,GACHgC,KAAK,CAAC,IAAM,QACf;IAEJ,OAAS;QACP;;;;;;;;KAQC,GACD;;;;;;KAMC,GACD,MAAM2B,YAAYX,SAASE,OAAOC,OAAO;QACzC,IAAIQ,aAAa,GAAG;QACpB,IAAIC,QAAQ5E,UACT6E,eAAe,CAACvF,gCAChBmE,KAAK,CAAC,UAAU,MAAM,WACtBA,KAAK,CAAC,cAAc,MAAMhD,OAC1BqE,OAAO,CAAC,cACRpB,KAAK,CAACqB,KAAKC,GAAG,CAACxF,WAAWmF;QAC7B,IAAIF,OAAOG,QAAQA,MAAMK,UAAU,CAACR;QACpC,MAAMS,OAAO,MAAMN,MAAM5D,GAAG;QAC5B,IAAIkE,KAAKC,KAAK,EAAE;QAEhB,KAAK,MAAMhF,OAAO+E,KAAKvB,IAAI,CAAE;gBAIlBxD;gBAA6BA;YAHtC+D,OAAOC,OAAO,IAAI;YAClBM,QAAQtE;YACR,MAAMJ,SACJyB,QAAOrB,WAAAA,IAAIa,GAAG,CAAC,qBAARb,WAAqB,iBAAQA,yBAAAA,IAAIS,GAAG,CAACwE,MAAM,CAACA,MAAM,qBAArBjF,uBAAuBoC,EAAE,mBAAI;YACnE,IAAI,CAACxC,QAAQ;YACb;;;;OAIC,GACD,IAAI,MAAMgE,KAAKsB,QAAQ,CAACtF,SAAS;gBAC/BmE,OAAOG,aAAa,IAAI;gBACxB;YACF;YACA,MAAM/C,aAAa,MAAMkB,oBAAoBrC,IAAIS,GAAG,EAAE;gBAAEH;YAAM;YAC9D,IAAI,CAACa,YAAY;gBACf4C,OAAOI,cAAc,IAAI;gBACzB;YACF;YACA,IAAI;gBACF,MAAMjE,QAAQiF,MAAM,CAAChE,YAAYnB,IAAIS,GAAG;gBACxCsD,OAAOE,OAAO,IAAI;YACpB,EAAE,OAAOR,OAAO;gBACd;;;;;;SAMC,GACDC,QAAQD,KAAK,CAAC,wBAAwBzD,IAAIS,GAAG,CAAC8D,IAAI,EAAEd;gBACpD,MAAMf,oBAAoB1C,IAAIS,GAAG,EAAEH,QAAQhB,qBAAqBgB;YAClE;QACF;QAEA,IAAIyD,OAAOC,OAAO,IAAIH,QAAQ;YAC5BE,OAAOK,QAAQ,GAAG;YAClBL,OAAOM,MAAM,GAAGC,QAAQ;gBAAEC,MAAMD,MAAM7D,GAAG,CAAC8D,IAAI;YAAC,IAAI;YACnD,OAAOR;QACT;QACA,IAAIgB,KAAKK,IAAI,GAAGR,KAAKC,GAAG,CAACxF,WAAWmF,YAAY;IAClD;IACA,OAAOT;AACT"}
+{"version":3,"sources":["../../../../../../../libs/plugins/workflows/src/lib/engine/flow-enrollments.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 * WHERE A PERSON WAITS, between one step of a flow and the next.\n *\n * An action used to be trigger → immediate steps, start to finish inside the\n * request that emitted the event. A `wait` step ends that: the run stops, and\n * something else has to pick it up minutes or weeks later. This module is the\n * something else's memory.\n *\n * ## The scheduling model, and why it survives a deploy\n *\n * There is no timer anywhere. A wait is a ROW — `resumeAtMs` on a document in\n * `hosts/{hostId}/flowEnrollments` — and the resume is a query for rows whose\n * time has come, run by the platform job beat that already exists. Nothing is\n * held in a process, so nothing is lost when the process ends: a deploy, a\n * restart, a cold start and a region failover all leave the row exactly where\n * it was, and the next beat finds it. The two worked examples in this repo\n * take the same shape for the same reason — `campaign-process-scheduled.ts`\n * claims `status: 'scheduled'` campaigns whose `sendAtMs` has passed, and the\n * abandoned-checkout scan re-reads any checkout it did not stamp.\n *\n * A beat that dies mid-resume is the case worth stating. The claim below flips\n * `waiting` → `running` in a transaction, so a second beat cannot pick up the\n * same enrollment; and a `running` row whose beat never came back is re-armed\n * by {@link FLOW_CLAIM_STALE_MS}, which is the difference between \"somebody is\n * working on this\" and \"somebody died holding this\".\n *\n * ## What it costs, which is not \"every enrollment on every beat\"\n *\n * The sweep reads DUE rows and only due rows: the query carries\n * `resumeAtMs <= now`, so a site with ten thousand people waiting three days\n * costs nothing on the beats before those three days are up. That is the whole\n * difference between this and the naive design, which re-reads every enrolled\n * person on every beat to ask whether their time has come.\n *\n * On top of that, {@link FLOW_RESUME_SCAN_BUDGET} bounds one beat's work and a\n * cursor resumes it — the shape `dynamic-list-materialize.ts` uses. The budget\n * matters even though the query is already narrow, because a due row that\n * cannot be acted on (a locked host) stays due: without paging past it, one\n * wall of locked rows at the head of the queue would starve every enrollment\n * behind it for as long as the lock lasted.\n *\n * ## ⛔ A BUDGET NEVER DROPS AN ENROLLMENT\n *\n * Running out of budget stops the sweep where it is. It never marks an\n * enrollment done, never advances its step, and never deletes it — the row\n * stays `waiting` and overdue, and the next beat starts again from the front\n * of the queue, which is where the oldest overdue work is. The same rule the\n * list materializer states: a bound on WORK is not a bound on PEOPLE.\n */\n\nimport { personKey } from '@aglyn/aglyn/server'\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport type { PluginJobHostGate } from '@aglyn/aglyn/server'\nimport type { WorkflowStep } from './workflow-steps'\n\n/**\n * `hosts/{hostId}/flowEnrollments/{actionId__personKey}` for an action,\n * `{workflow-<workflowId>__personKey}` for a workflow, and\n * `{org-<automationId>__personKey}` for an org automation waiting on the site\n * it ran on.\n */\nexport const FLOW_ENROLLMENTS_SUBCOLLECTION = 'flowEnrollments'\n\n/**\n * What is waiting, when it is not a site action: `workflow` for a workflow's\n * run and `org` for an org automation's (AGL-3302).\n */\nexport type FlowEnrollmentAutomation = 'workflow' | 'org'\n\n/**\n * Documents one sweep may READ across every site.\n *\n * A bound on work, not on membership — see the note above. Sized well past a\n * normal beat's due queue so the ordinary case never pages at all, and far\n * short of what one API invocation should spend.\n */\nexport const FLOW_RESUME_SCAN_BUDGET = 500\n\n/** Due enrollments read per page. */\nconst PAGE_SIZE = 50\n\n/**\n * How long a claim may go unfinished before another beat may take it.\n *\n * A `running` row is one a beat is part-way through. If that beat's process\n * ends — a deploy mid-resume, a function timeout, an unhandled throw that\n * escaped the isolation — nothing ever clears the flag, and without this the\n * enrollment would be stranded `running` for ever: not waiting, so no sweep\n * finds it; not done, so nobody is told.\n *\n * Ten minutes is far longer than a resume takes (a handful of Firestore reads\n * and at most one email) and far shorter than the shortest wait anybody\n * authors, so the only thing it can re-arm is a claim nobody is holding.\n *\n * The cost of getting it wrong is a step running twice, which is why the\n * window is generous rather than tight.\n */\nexport const FLOW_CLAIM_STALE_MS = 10 * 60_000\n\nexport type FlowEnrollmentStatus = 'waiting' | 'running'\n\n/**\n * Why an enrollment ended. Recorded on the run history, never on the\n * enrollment — the row is deleted when the flow ends, so the activity\n * collection is where \"what happened to this person\" lives.\n */\nexport type FlowEnrollmentEnding =\n  /** Every remaining step ran. */\n  | 'completed'\n  /** An `exitFlow` step, or a guard that ended the run. */\n  | 'exited'\n  /** The action was deleted, disabled, or lost its entitlement. */\n  | 'flow-stopped'\n\nexport interface FlowEnrollment {\n  hostId: string\n  /**\n   * What is waiting: `workflow` for a workflow's run, `org` for an org\n   * automation's, absent for an action's — which is every enrollment written\n   * before a workflow could wait, so an absent field is read as an action for\n   * as long as those rows exist.\n   */\n  automation?: FlowEnrollmentAutomation\n  /**\n   * The organization whose automation this is, on an `org` enrollment: the\n   * resume re-reads `orgs/{orgId}/automations/{actionId}`, and refuses to\n   * continue for a site that has since left the organization.\n   */\n  orgId?: string\n  /** The automation's document id: the action's, the workflow's or the org automation's. */\n  actionId: string\n  actionName: string\n  status: FlowEnrollmentStatus\n  /** When this flow continues. ALWAYS set — the sweep orders on it. */\n  resumeAtMs: number\n  /** Index into {@link steps} of the step that runs on resume. */\n  nextStepIndex: number\n  /**\n   * THE FLOW AS IT WAS WHEN THIS PERSON ENTERED IT.\n   *\n   * Not a reference to the action's current steps, and this is the whole\n   * answer to \"what happens to a flow somebody is already waiting inside\".\n   * `nextStepIndex` is a position in a LIST, and an author who reorders,\n   * inserts or deletes a step moves every position after it — so resuming a\n   * three-day wait against the edited list would deliver whatever now happens\n   * to sit at index 4. That is not a changed flow, it is a scrambled one, and\n   * the person it happens to is the one who cannot see it.\n   *\n   * So an edit applies to everyone who enrolls AFTER it, and nobody who is\n   * already inside. The trade is that a merchant who fixes a typo in step 3\n   * does not fix it for the people mid-wait; the alternative trade is sending\n   * them a step from a different flow, which is worse and silent.\n   *\n   * Bounded by `ACTION_MAX_STEPS` for an action, so the snapshot is ten\n   * small objects, and by `WORKFLOW_MAX_STEPS` for a workflow, whose snapshot\n   * holds its function calls beside its Actions steps.\n   */\n  steps: WorkflowStep[]\n  /** The event a `waitForEvent` is watching for; absent for a plain wait. */\n  awaitingEvent?: string | null\n  /** `sha256` of the person's address — the wake lookup key. */\n  personKey: string\n  email: string\n  /** The trigger payload, carried forward so later steps see the same scope. */\n  payload: Record<string, unknown>\n  /** The event that started the flow, for the run-history line. */\n  event: string\n  enrolledAtMs: number\n  updatedAtMs: number\n  /** How many times this enrollment has been picked up. */\n  resumes: number\n  /** Set while `running`; how {@link FLOW_CLAIM_STALE_MS} is measured. */\n  claimedAtMs?: number\n}\n\n/**\n * ONE LIVE ENROLLMENT PER PERSON PER FLOW, by construction.\n *\n * The document id is derived rather than generated, so a second concurrent\n * enrollment is not a race to detect — it is a write to a document that\n * already exists. A shopper who abandons three carts in an hour gets one\n * recovery sequence, not three overlapping ones, and the guarantee holds\n * across processes because it is Firestore's and not a lock of ours.\n *\n * DELIBERATE, and reversible: a flow that genuinely wants concurrent\n * enrollments would key on something narrower than the person (the cart, the\n * order), which is a change to this function and to nothing else.\n */\nexport function flowEnrollmentId(\n  actionId: string,\n  key: string,\n  automation?: FlowEnrollmentAutomation,\n): string {\n  // Each kind's id is kept apart from the others', so no two kinds can ever\n  // share a row whatever ids their collections hand out — an org automation's\n  // id comes from a different collection than the site's own action ids.\n  if (automation === 'workflow') return `workflow-${actionId}__${key}`\n  if (automation === 'org') return `org-${actionId}__${key}`\n  return `${actionId}__${key}`\n}\n\nfunction enrollmentsRef(\n  hostId: string,\n  firestore?: any,\n): FirebaseFirestore.CollectionReference {\n  return (firestore ?? firebaseAdmin.app().firestore())\n    .collection('hosts')\n    .doc(hostId)\n    .collection(FLOW_ENROLLMENTS_SUBCOLLECTION)\n}\n\nexport interface EnrollInFlowOptions {\n  hostId: string\n  /** `workflow` for a workflow's run, `org` for an org automation's; absent for an action's. */\n  automation?: FlowEnrollmentAutomation\n  /** The owning organization, on an `org` enrollment. */\n  orgId?: string\n  /** The automation's document id. */\n  actionId: string\n  action: { name?: string; steps?: readonly WorkflowStep[] }\n  /** The address the flow is about. A flow with no person cannot wait. */\n  email: string\n  event: string\n  payload: Record<string, unknown>\n  /** Index of the step that runs when the wait ends. */\n  nextStepIndex: number\n  resumeAtMs: number\n  awaitingEvent?: string | null\n  nowMs?: number\n  firestore?: any\n}\n\nexport type EnrollInFlowResult =\n  | { enrolled: true; id: string }\n  | { enrolled: false; reason: 'no-person' | 'already-waiting' }\n\n/**\n * Suspends a run, durably.\n *\n * Refuses rather than improvises when there is nobody to wait for. A flow\n * that waits is a flow that continues later for a PERSON — it is how the\n * enrollment is keyed, how a `waitForEvent` is woken, and who the next step's\n * email is addressed to. An anonymous wait would have no dedupe key, so a\n * page-view trigger on a busy site would mint an enrollment per visit; and\n * nothing downstream could use it. Saying so is better than silently\n * enrolling nobody.\n */\nexport async function enrollInFlow(\n  options: EnrollInFlowOptions,\n): Promise<EnrollInFlowResult> {\n  const key = personKey(options.email)\n  if (!key) return { enrolled: false, reason: 'no-person' }\n  const nowMs = options.nowMs ?? Date.now()\n  const ref = enrollmentsRef(options.hostId, options.firestore).doc(\n    flowEnrollmentId(options.actionId, key, options.automation),\n  )\n  const firestore = options.firestore ?? firebaseAdmin.app().firestore()\n  return await firestore.runTransaction(\n    async (transaction: FirebaseFirestore.Transaction) => {\n      const existing = await transaction.get(ref)\n      /*\n       * A row that is `waiting` or freshly `running` belongs to a live\n       * enrollment and this one is a duplicate. A STALE `running` row is a\n       * claim nobody is holding (see FLOW_CLAIM_STALE_MS) and a completed\n       * flow deletes its row, so anything else is free to be overwritten —\n       * which is what lets the same person go through the same welcome series\n       * again next year.\n       */\n      if (existing.exists) {\n        const status = existing.get('status')\n        const claimedAtMs = Number(existing.get('claimedAtMs') ?? 0)\n        const live =\n          status === 'waiting' ||\n          (status === 'running' && nowMs - claimedAtMs < FLOW_CLAIM_STALE_MS)\n        if (live) {\n          return { enrolled: false, reason: 'already-waiting' as const }\n        }\n      }\n      const enrollment: FlowEnrollment = {\n        hostId: options.hostId,\n        ...(options.automation ? { automation: options.automation } : {}),\n        ...(options.automation === 'org' && options.orgId\n          ? { orgId: options.orgId }\n          : {}),\n        actionId: options.actionId,\n        actionName: String(options.action.name ?? ''),\n        status: 'waiting',\n        resumeAtMs: options.resumeAtMs,\n        nextStepIndex: options.nextStepIndex,\n        steps: [...(options.action.steps ?? [])],\n        personKey: key,\n        email: String(options.email).trim().toLowerCase(),\n        payload: options.payload ?? {},\n        event: options.event,\n        enrolledAtMs: nowMs,\n        updatedAtMs: nowMs,\n        resumes: 0,\n        ...(options.awaitingEvent\n          ? { awaitingEvent: options.awaitingEvent }\n          : { awaitingEvent: null }),\n      }\n      // `set`, not `create`: the transaction above has already decided this id\n      // is free, and a completed flow's deleted row may be re-enrolled.\n      transaction.set(ref, enrollment)\n      return { enrolled: true as const, id: ref.id }\n    },\n  )\n}\n\n/**\n * Takes an enrollment out of the queue for this beat, or answers null.\n *\n * The claim and the read are one transaction, so two beats — an overlapping\n * schedule, a retried invocation, two regions — cannot both resume the same\n * person. `campaign-process-scheduled.ts` claims a due campaign exactly this\n * way and for exactly this reason.\n */\nexport async function claimFlowEnrollment(\n  ref: FirebaseFirestore.DocumentReference,\n  options?: { nowMs?: number; firestore?: any },\n): Promise<FlowEnrollment | null> {\n  const nowMs = options?.nowMs ?? Date.now()\n  const firestore =\n    options?.firestore ?? ref.firestore ?? firebaseAdmin.app().firestore()\n  return await firestore.runTransaction(\n    async (transaction: FirebaseFirestore.Transaction) => {\n      const fresh = await transaction.get(ref)\n      if (!fresh.exists) return null\n      const status = fresh.get('status')\n      const claimedAtMs = Number(fresh.get('claimedAtMs') ?? 0)\n      const claimable =\n        status === 'waiting' ||\n        (status === 'running' && nowMs - claimedAtMs >= FLOW_CLAIM_STALE_MS)\n      if (!claimable) return null\n      transaction.update(ref, {\n        status: 'running',\n        claimedAtMs: nowMs,\n        updatedAtMs: nowMs,\n      })\n      return { ...(fresh.data() as FlowEnrollment), status: 'running' }\n    },\n  )\n}\n\n/**\n * Puts a claimed enrollment back without having run it.\n *\n * SKIPPED, NOT DROPPED. Used when the resume cannot proceed for a reason a\n * later beat may pass — the platform's hourly send ceiling had no room, the\n * recipient's own frequency window is full — so the step is attempted again\n * rather than lost. `retryAtMs` pushes the row down the queue so it does not\n * spin on the same refusal every minute.\n */\nexport async function deferFlowEnrollment(\n  ref: FirebaseFirestore.DocumentReference,\n  retryAtMs: number,\n  nowMs = Date.now(),\n): Promise<void> {\n  await ref\n    .set(\n      {\n        status: 'waiting',\n        resumeAtMs: retryAtMs,\n        claimedAtMs: null,\n        updatedAtMs: nowMs,\n      },\n      { merge: true },\n    )\n    .catch(() => undefined)\n}\n\n/** Advances a claimed enrollment to the next wait, keeping it in the queue. */\nexport async function advanceFlowEnrollment(\n  ref: FirebaseFirestore.DocumentReference,\n  update: {\n    nextStepIndex: number\n    resumeAtMs: number\n    awaitingEvent?: string | null\n    payload?: Record<string, unknown>\n  },\n  nowMs = Date.now(),\n): Promise<void> {\n  await ref\n    .set(\n      {\n        status: 'waiting',\n        claimedAtMs: null,\n        updatedAtMs: nowMs,\n        resumes: firebaseAdmin.firestore.FieldValue.increment(1),\n        nextStepIndex: update.nextStepIndex,\n        resumeAtMs: update.resumeAtMs,\n        awaitingEvent: update.awaitingEvent ?? null,\n        ...(update.payload ? { payload: update.payload } : {}),\n      },\n      { merge: true },\n    )\n    .catch(() => undefined)\n}\n\n/**\n * Ends an enrollment by DELETING it.\n *\n * The row is live state, not a record. What happened to this person is\n * already written to `hosts/{hostId}/activity` — the same run history every\n * immediate action writes — so keeping a `done` row would be a second,\n * shorter answer to a question that is already answered, growing for ever in\n * a collection the sweep has to index.\n *\n * Deleting is also what lets the same person enter the same flow again: the\n * id is derived from the person, so a tombstone would be a permanent refusal\n * to ever run this sequence for them a second time.\n */\nexport async function endFlowEnrollment(\n  ref: FirebaseFirestore.DocumentReference,\n): Promise<void> {\n  await ref.delete().catch(() => undefined)\n}\n\n/**\n * The enrollments this person's event should wake, on this site.\n *\n * Keyed, bounded and cheap: three equality filters and a small limit, which\n * Firestore serves by merging single-field indexes. This is what keeps\n * `waitForEvent` off a polling design — nothing scans the enrolled population\n * looking for a match, the event arrives already knowing who it is about.\n *\n * The CALLER decides whether to ask at all. `runEventActions` fires on every\n * page view of every published site, so asking on every event would be a\n * query per visitor; it asks only when the payload names a person, which a\n * page view does not.\n */\nexport async function findFlowEnrollmentsAwaiting(options: {\n  hostId: string\n  event: string\n  email: string\n  firestore?: any\n  limit?: number\n}): Promise<FirebaseFirestore.QueryDocumentSnapshot[]> {\n  const key = personKey(options.email)\n  const event = String(options.event ?? '').trim()\n  if (!key || !event || !options.hostId) return []\n  try {\n    const snapshot = await enrollmentsRef(options.hostId, options.firestore)\n      .where('awaitingEvent', '==', event)\n      .where('personKey', '==', key)\n      .where('status', '==', 'waiting')\n      .limit(options.limit ?? 5)\n      .get()\n    return snapshot.docs\n  } catch (error) {\n    console.error('[flow] awaiting-event lookup failed', options.hostId, error)\n    return []\n  }\n}\n\n/** Where a partial sweep stopped, so the next beat resumes rather than restarts. */\nexport interface FlowSweepCursor {\n  /** Full document path of the last enrollment read. */\n  path: string\n}\n\nexport interface FlowSweepResult {\n  /** Due enrollments read, against the budget. */\n  scanned: number\n  /** Enrollments this beat claimed and ran. */\n  resumed: number\n  /** Rows left untouched because their site is locked. */\n  skippedLocked: number\n  /** Rows another beat already held. */\n  skippedClaimed: number\n  /** False when the scan budget ran out — `cursor` says where to resume. */\n  complete: boolean\n  cursor: FlowSweepCursor | null\n}\n\n/**\n * One pass over the flows whose wait has ended.\n *\n * The RESUME itself is injected. Running a step needs the action executor,\n * which needs entitlements, datasets, webhooks and the mail path; keeping it\n * out of this function is what lets the scheduling contract — due-ness, the\n * claim, the budget, the lock — be exercised without any of that.\n */\nexport async function sweepDueFlowEnrollments(\n  gate: PluginJobHostGate,\n  options: {\n    resume: (\n      enrollment: FlowEnrollment,\n      ref: FirebaseFirestore.DocumentReference,\n    ) => Promise<void>\n    nowMs?: number\n    scanBudget?: number\n    cursor?: FlowSweepCursor | null\n    firestore?: any\n  },\n): Promise<FlowSweepResult> {\n  const firestore = options.firestore ?? firebaseAdmin.app().firestore()\n  const nowMs = options.nowMs ?? Date.now()\n  const budget = options.scanBudget ?? FLOW_RESUME_SCAN_BUDGET\n  const result: FlowSweepResult = {\n    scanned: 0,\n    resumed: 0,\n    skippedLocked: 0,\n    skippedClaimed: 0,\n    complete: true,\n    cursor: null,\n  }\n  let after: FirebaseFirestore.DocumentSnapshot | null = options.cursor?.path\n    ? await firestore\n        .doc(options.cursor.path)\n        .get()\n        .catch(() => null)\n    : null\n\n  for (;;) {\n    /*\n     * Ordered by `resumeAtMs`, which every writer in this module sets on\n     * every write. That is load-bearing twice over: an `orderBy` on a field\n     * DROPS documents that lack it, so a writer that ever omitted it would\n     * make those enrollments invisible to the only thing that resumes them;\n     * and ordering oldest-due-first is what makes a budget fair, because the\n     * work a short beat leaves behind is the newest rather than whichever\n     * rows Firestore happened to return.\n     */\n    /*\n     * The page is capped by what is LEFT of the budget, not only by\n     * `PAGE_SIZE`. Checking the budget between pages would let a run whose\n     * budget is smaller than one page read the whole page first — the budget\n     * would then describe how much was reported rather than how much was\n     * read, which is the opposite of what a read budget is for.\n     */\n    const remaining = budget - result.scanned\n    if (remaining <= 0) break\n    let query = firestore\n      .collectionGroup(FLOW_ENROLLMENTS_SUBCOLLECTION)\n      .where('status', '==', 'waiting')\n      .where('resumeAtMs', '<=', nowMs)\n      .orderBy('resumeAtMs')\n      .limit(Math.min(PAGE_SIZE, remaining))\n    if (after) query = query.startAfter(after)\n    const page = await query.get()\n    if (page.empty) break\n\n    for (const doc of page.docs) {\n      result.scanned += 1\n      after = doc\n      const hostId =\n        String(doc.get('hostId') ?? '') || (doc.ref.parent.parent?.id ?? '')\n      if (!hostId) continue\n      /*\n       * LOCKDOWN, first in the loop body and before any write. `continue`\n       * leaves the row `waiting` and overdue, so the flow resumes on the\n       * first beat after the lift rather than being cancelled by a pause.\n       */\n      if (await gate.isLocked(hostId)) {\n        result.skippedLocked += 1\n        continue\n      }\n      const enrollment = await claimFlowEnrollment(doc.ref, { nowMs })\n      if (!enrollment) {\n        result.skippedClaimed += 1\n        continue\n      }\n      try {\n        await options.resume(enrollment, doc.ref)\n        result.resumed += 1\n      } catch (error) {\n        /*\n         * One broken flow must not stop the sweep — the same isolation the\n         * dynamic-list sweep gives each list. The claim is released so a\n         * later beat retries; a permanently broken step therefore retries for\n         * as long as the enrollment lives, which is bounded by its own wait\n         * ceiling and is the recoverable direction.\n         */\n        console.error('[flow] resume failed', doc.ref.path, error)\n        await deferFlowEnrollment(doc.ref, nowMs + FLOW_CLAIM_STALE_MS, nowMs)\n      }\n    }\n\n    if (result.scanned >= budget) {\n      result.complete = false\n      result.cursor = after ? { path: after.ref.path } : null\n      return result\n    }\n    if (page.size < Math.min(PAGE_SIZE, remaining)) break\n  }\n  return result\n}\n"],"names":["personKey","firebaseAdmin","FLOW_ENROLLMENTS_SUBCOLLECTION","FLOW_RESUME_SCAN_BUDGET","PAGE_SIZE","FLOW_CLAIM_STALE_MS","flowEnrollmentId","actionId","key","automation","enrollmentsRef","hostId","firestore","app","collection","doc","enrollInFlow","options","email","enrolled","reason","nowMs","Date","now","ref","runTransaction","transaction","existing","get","exists","status","claimedAtMs","Number","live","enrollment","orgId","actionName","String","action","name","resumeAtMs","nextStepIndex","steps","trim","toLowerCase","payload","event","enrolledAtMs","updatedAtMs","resumes","awaitingEvent","set","id","claimFlowEnrollment","fresh","claimable","update","data","deferFlowEnrollment","retryAtMs","merge","catch","undefined","advanceFlowEnrollment","FieldValue","increment","endFlowEnrollment","delete","findFlowEnrollmentsAwaiting","snapshot","where","limit","docs","error","console","sweepDueFlowEnrollments","gate","budget","scanBudget","result","scanned","resumed","skippedLocked","skippedClaimed","complete","cursor","after","path","remaining","query","collectionGroup","orderBy","Math","min","startAfter","page","empty","parent","isLocked","resume","size"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgDC,GAED,SAASA,SAAS,QAAQ,sBAAqB;AAC/C,SAASC,aAAa,QAAQ,2BAA0B;AAIxD;;;;;CAKC,GACD,OAAO,MAAMC,iCAAiC,kBAAiB;AAQ/D;;;;;;CAMC,GACD,OAAO,MAAMC,0BAA0B,IAAG;AAE1C,mCAAmC,GACnC,MAAMC,YAAY;AAElB;;;;;;;;;;;;;;;CAeC,GACD,OAAO,MAAMC,sBAAsB,KAAK,MAAM;AA8E9C;;;;;;;;;;;;CAYC,GACD,OAAO,SAASC,iBACdC,QAAgB,EAChBC,GAAW,EACXC,UAAqC;IAErC,0EAA0E;IAC1E,4EAA4E;IAC5E,uEAAuE;IACvE,IAAIA,eAAe,YAAY,OAAO,CAAC,SAAS,EAAEF,SAAS,EAAE,EAAEC,KAAK;IACpE,IAAIC,eAAe,OAAO,OAAO,CAAC,IAAI,EAAEF,SAAS,EAAE,EAAEC,KAAK;IAC1D,OAAO,GAAGD,SAAS,EAAE,EAAEC,KAAK;AAC9B;AAEA,SAASE,eACPC,MAAc,EACdC,SAAe;IAEf,OAAO,CAACA,oBAAAA,YAAaX,cAAcY,GAAG,GAAGD,SAAS,IAC/CE,UAAU,CAAC,SACXC,GAAG,CAACJ,QACJG,UAAU,CAACZ;AAChB;AA2BA;;;;;;;;;;CAUC,GACD,OAAO,eAAec,aACpBC,OAA4B;QAIdA,gBAIIA;IANlB,MAAMT,MAAMR,UAAUiB,QAAQC,KAAK;IACnC,IAAI,CAACV,KAAK,OAAO;QAAEW,UAAU;QAAOC,QAAQ;IAAY;IACxD,MAAMC,SAAQJ,iBAAAA,QAAQI,KAAK,YAAbJ,iBAAiBK,KAAKC,GAAG;IACvC,MAAMC,MAAMd,eAAeO,QAAQN,MAAM,EAAEM,QAAQL,SAAS,EAAEG,GAAG,CAC/DT,iBAAiBW,QAAQV,QAAQ,EAAEC,KAAKS,QAAQR,UAAU;IAE5D,MAAMG,aAAYK,qBAAAA,QAAQL,SAAS,YAAjBK,qBAAqBhB,cAAcY,GAAG,GAAGD,SAAS;IACpE,OAAO,MAAMA,UAAUa,cAAc,CACnC,OAAOC;YA2BgBT,sBAIPA,uBAGHA;QAjCX,MAAMU,WAAW,MAAMD,YAAYE,GAAG,CAACJ;QACvC;;;;;;;OAOC,GACD,IAAIG,SAASE,MAAM,EAAE;gBAEQF;YAD3B,MAAMG,SAASH,SAASC,GAAG,CAAC;YAC5B,MAAMG,cAAcC,QAAOL,gBAAAA,SAASC,GAAG,CAAC,0BAAbD,gBAA+B;YAC1D,MAAMM,OACJH,WAAW,aACVA,WAAW,aAAaT,QAAQU,cAAc1B;YACjD,IAAI4B,MAAM;gBACR,OAAO;oBAAEd,UAAU;oBAAOC,QAAQ;gBAA2B;YAC/D;QACF;QACA,MAAMc,aAA6B;YACjCvB,QAAQM,QAAQN,MAAM;WAClBM,QAAQR,UAAU,GAAG;YAAEA,YAAYQ,QAAQR,UAAU;QAAC,IAAI,CAAC,GAC3DQ,QAAQR,UAAU,KAAK,SAASQ,QAAQkB,KAAK,GAC7C;YAAEA,OAAOlB,QAAQkB,KAAK;QAAC,IACvB,CAAC;YACL5B,UAAUU,QAAQV,QAAQ;YAC1B6B,YAAYC,QAAOpB,uBAAAA,QAAQqB,MAAM,CAACC,IAAI,YAAnBtB,uBAAuB;YAC1Ca,QAAQ;YACRU,YAAYvB,QAAQuB,UAAU;YAC9BC,eAAexB,QAAQwB,aAAa;YACpCC,OAAO;oBAAKzB,wBAAAA,QAAQqB,MAAM,CAACI,KAAK,YAApBzB,wBAAwB,EAAE;aAAE;YACxCjB,WAAWQ;YACXU,OAAOmB,OAAOpB,QAAQC,KAAK,EAAEyB,IAAI,GAAGC,WAAW;YAC/CC,OAAO,GAAE5B,mBAAAA,QAAQ4B,OAAO,YAAf5B,mBAAmB,CAAC;YAC7B6B,OAAO7B,QAAQ6B,KAAK;YACpBC,cAAc1B;YACd2B,aAAa3B;YACb4B,SAAS;WACLhC,QAAQiC,aAAa,GACrB;YAAEA,eAAejC,QAAQiC,aAAa;QAAC,IACvC;YAAEA,eAAe;QAAK;QAE5B,yEAAyE;QACzE,kEAAkE;QAClExB,YAAYyB,GAAG,CAAC3B,KAAKU;QACrB,OAAO;YAAEf,UAAU;YAAeiC,IAAI5B,IAAI4B,EAAE;QAAC;IAC/C;AAEJ;AAEA;;;;;;;CAOC,GACD,OAAO,eAAeC,oBACpB7B,GAAwC,EACxCP,OAA6C;cAI3CA;IAFF,MAAMI,gBAAQJ,2BAAAA,QAASI,KAAK,mBAAIC,KAAKC,GAAG;IACxC,MAAMX,aACJK,iBAAAA,2BAAAA,QAASL,SAAS,oBAAIY,IAAIZ,SAAS,YAAnCK,QAAuChB,cAAcY,GAAG,GAAGD,SAAS;IACtE,OAAO,MAAMA,UAAUa,cAAc,CACnC,OAAOC;YAIsB4B;QAH3B,MAAMA,QAAQ,MAAM5B,YAAYE,GAAG,CAACJ;QACpC,IAAI,CAAC8B,MAAMzB,MAAM,EAAE,OAAO;QAC1B,MAAMC,SAASwB,MAAM1B,GAAG,CAAC;QACzB,MAAMG,cAAcC,QAAOsB,aAAAA,MAAM1B,GAAG,CAAC,0BAAV0B,aAA4B;QACvD,MAAMC,YACJzB,WAAW,aACVA,WAAW,aAAaT,QAAQU,eAAe1B;QAClD,IAAI,CAACkD,WAAW,OAAO;QACvB7B,YAAY8B,MAAM,CAAChC,KAAK;YACtBM,QAAQ;YACRC,aAAaV;YACb2B,aAAa3B;QACf;QACA,OAAO,aAAMiC,MAAMG,IAAI;YAAuB3B,QAAQ;;IACxD;AAEJ;AAEA;;;;;;;;CAQC,GACD,OAAO,eAAe4B,oBACpBlC,GAAwC,EACxCmC,SAAiB,EACjBtC,QAAQC,KAAKC,GAAG,EAAE;IAElB,MAAMC,IACH2B,GAAG,CACF;QACErB,QAAQ;QACRU,YAAYmB;QACZ5B,aAAa;QACbiB,aAAa3B;IACf,GACA;QAAEuC,OAAO;IAAK,GAEfC,KAAK,CAAC,IAAMC;AACjB;AAEA,6EAA6E,GAC7E,OAAO,eAAeC,sBACpBvC,GAAwC,EACxCgC,MAKC,EACDnC,QAAQC,KAAKC,GAAG,EAAE;QAWGiC;IATrB,MAAMhC,IACH2B,GAAG,CACF;QACErB,QAAQ;QACRC,aAAa;QACbiB,aAAa3B;QACb4B,SAAShD,cAAcW,SAAS,CAACoD,UAAU,CAACC,SAAS,CAAC;QACtDxB,eAAee,OAAOf,aAAa;QACnCD,YAAYgB,OAAOhB,UAAU;QAC7BU,aAAa,GAAEM,wBAAAA,OAAON,aAAa,YAApBM,wBAAwB;OACnCA,OAAOX,OAAO,GAAG;QAAEA,SAASW,OAAOX,OAAO;IAAC,IAAI,CAAC,IAEtD;QAAEe,OAAO;IAAK,GAEfC,KAAK,CAAC,IAAMC;AACjB;AAEA;;;;;;;;;;;;CAYC,GACD,OAAO,eAAeI,kBACpB1C,GAAwC;IAExC,MAAMA,IAAI2C,MAAM,GAAGN,KAAK,CAAC,IAAMC;AACjC;AAEA;;;;;;;;;;;;CAYC,GACD,OAAO,eAAeM,4BAA4BnD,OAMjD;QAEsBA;IADrB,MAAMT,MAAMR,UAAUiB,QAAQC,KAAK;IACnC,MAAM4B,QAAQT,QAAOpB,iBAAAA,QAAQ6B,KAAK,YAAb7B,iBAAiB,IAAI0B,IAAI;IAC9C,IAAI,CAACnC,OAAO,CAACsC,SAAS,CAAC7B,QAAQN,MAAM,EAAE,OAAO,EAAE;IAChD,IAAI;YAKOM;QAJT,MAAMoD,WAAW,MAAM3D,eAAeO,QAAQN,MAAM,EAAEM,QAAQL,SAAS,EACpE0D,KAAK,CAAC,iBAAiB,MAAMxB,OAC7BwB,KAAK,CAAC,aAAa,MAAM9D,KACzB8D,KAAK,CAAC,UAAU,MAAM,WACtBC,KAAK,EAACtD,iBAAAA,QAAQsD,KAAK,YAAbtD,iBAAiB,GACvBW,GAAG;QACN,OAAOyC,SAASG,IAAI;IACtB,EAAE,OAAOC,OAAO;QACdC,QAAQD,KAAK,CAAC,uCAAuCxD,QAAQN,MAAM,EAAE8D;QACrE,OAAO,EAAE;IACX;AACF;AAsBA;;;;;;;CAOC,GACD,OAAO,eAAeE,wBACpBC,IAAuB,EACvB3D,OASC;QAEiBA,oBACJA,gBACCA;QASwCA;IAXvD,MAAML,aAAYK,qBAAAA,QAAQL,SAAS,YAAjBK,qBAAqBhB,cAAcY,GAAG,GAAGD,SAAS;IACpE,MAAMS,SAAQJ,iBAAAA,QAAQI,KAAK,YAAbJ,iBAAiBK,KAAKC,GAAG;IACvC,MAAMsD,UAAS5D,sBAAAA,QAAQ6D,UAAU,YAAlB7D,sBAAsBd;IACrC,MAAM4E,SAA0B;QAC9BC,SAAS;QACTC,SAAS;QACTC,eAAe;QACfC,gBAAgB;QAChBC,UAAU;QACVC,QAAQ;IACV;IACA,IAAIC,QAAmDrE,EAAAA,kBAAAA,QAAQoE,MAAM,qBAAdpE,gBAAgBsE,IAAI,IACvE,MAAM3E,UACHG,GAAG,CAACE,QAAQoE,MAAM,CAACE,IAAI,EACvB3D,GAAG,GACHiC,KAAK,CAAC,IAAM,QACf;IAEJ,OAAS;QACP;;;;;;;;KAQC,GACD;;;;;;KAMC,GACD,MAAM2B,YAAYX,SAASE,OAAOC,OAAO;QACzC,IAAIQ,aAAa,GAAG;QACpB,IAAIC,QAAQ7E,UACT8E,eAAe,CAACxF,gCAChBoE,KAAK,CAAC,UAAU,MAAM,WACtBA,KAAK,CAAC,cAAc,MAAMjD,OAC1BsE,OAAO,CAAC,cACRpB,KAAK,CAACqB,KAAKC,GAAG,CAACzF,WAAWoF;QAC7B,IAAIF,OAAOG,QAAQA,MAAMK,UAAU,CAACR;QACpC,MAAMS,OAAO,MAAMN,MAAM7D,GAAG;QAC5B,IAAImE,KAAKC,KAAK,EAAE;QAEhB,KAAK,MAAMjF,OAAOgF,KAAKvB,IAAI,CAAE;gBAIlBzD;gBAA6BA;YAHtCgE,OAAOC,OAAO,IAAI;YAClBM,QAAQvE;YACR,MAAMJ,SACJ0B,QAAOtB,WAAAA,IAAIa,GAAG,CAAC,qBAARb,WAAqB,iBAAQA,yBAAAA,IAAIS,GAAG,CAACyE,MAAM,CAACA,MAAM,qBAArBlF,uBAAuBqC,EAAE,mBAAI;YACnE,IAAI,CAACzC,QAAQ;YACb;;;;OAIC,GACD,IAAI,MAAMiE,KAAKsB,QAAQ,CAACvF,SAAS;gBAC/BoE,OAAOG,aAAa,IAAI;gBACxB;YACF;YACA,MAAMhD,aAAa,MAAMmB,oBAAoBtC,IAAIS,GAAG,EAAE;gBAAEH;YAAM;YAC9D,IAAI,CAACa,YAAY;gBACf6C,OAAOI,cAAc,IAAI;gBACzB;YACF;YACA,IAAI;gBACF,MAAMlE,QAAQkF,MAAM,CAACjE,YAAYnB,IAAIS,GAAG;gBACxCuD,OAAOE,OAAO,IAAI;YACpB,EAAE,OAAOR,OAAO;gBACd;;;;;;SAMC,GACDC,QAAQD,KAAK,CAAC,wBAAwB1D,IAAIS,GAAG,CAAC+D,IAAI,EAAEd;gBACpD,MAAMf,oBAAoB3C,IAAIS,GAAG,EAAEH,QAAQhB,qBAAqBgB;YAClE;QACF;QAEA,IAAI0D,OAAOC,OAAO,IAAIH,QAAQ;YAC5BE,OAAOK,QAAQ,GAAG;YAClBL,OAAOM,MAAM,GAAGC,QAAQ;gBAAEC,MAAMD,MAAM9D,GAAG,CAAC+D,IAAI;YAAC,IAAI;YACnD,OAAOR;QACT;QACA,IAAIgB,KAAKK,IAAI,GAAGR,KAAKC,GAAG,CAACzF,WAAWoF,YAAY;IAClD;IACA,OAAOT;AACT"}

package/src/lib/engine/run-event-actions.d.ts

@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { type HostActionAlert, type HostFunction, type HostVariable, type HostWorkflow, type PluginJobHostGate } from '@aglyn/aglyn/server';
+import { type HostAction, type HostActionAlert, type HostActionStep, type HostFunction, type HostVariable, type HostWorkflow, type PluginJobHostGate } from '@aglyn/aglyn/server';
 import { type FlowEnrollment, type FlowSweepCursor, type FlowSweepResult } from './flow-enrollments';
 import type { HostEventPayload } from '@aglyn/tenant-runtime/host-event-listeners';
 import { type AutomationWorkflow, type WorkflowStep } from './workflow-steps';
@@ -70,9 +70,15 @@ export interface WorkflowContext {
  * its document id, and its name for the history and the enrollment.
  */
 export interface AutomationRun {
-    kind: 'action' | 'workflow';
+    /**
+     * `orgAutomation` for an org automation (AGL-3302) — a run on the event's
+     * site of an automation the organization placed there.
+     */
+    kind: 'action' | 'workflow' | 'orgAutomation';
     id: string;
     name: string;
+    /** The owning organization, on an `orgAutomation` run: a wait enrolls with it. */
+    orgId?: string;
 }
 /**
  * The run environment for one automation run: the org's plan gates resolved
@@ -97,6 +103,36 @@ export declare function makeWorkflowContextLoader(hostRef: FirebaseFirestore.Doc
 export declare function workflowContextFromDocs(functionDocs: readonly FirebaseFirestore.QueryDocumentSnapshot[], variableDocs: readonly FirebaseFirestore.QueryDocumentSnapshot[], workflowDocs: readonly FirebaseFirestore.QueryDocumentSnapshot[]): WorkflowContext;
 /** How a run of an action's step list ended. */
 type ActionRunEnding = 'ran' | 'waiting' | 'exited' | 'deferred';
+interface ExecuteActionOptions {
+    /**
+     * The step to start at. Non-zero only on a resume, where it is the
+     * enrollment's `nextStepIndex`.
+     */
+    startIndex?: number;
+    /**
+     * The step list to run.
+     *
+     * A resume passes the enrollment's SNAPSHOT rather than the action's
+     * current steps — see `FlowEnrollment.steps` for why a position in a list
+     * is meaningless against a list that has since been edited.
+     */
+    steps?: readonly HostActionStep[];
+    /**
+     * The enrollment this run belongs to. Present only on a resume; a first run
+     * mints one if it reaches a wait.
+     */
+    enrollmentRef?: FirebaseFirestore.DocumentReference | null;
+    /**
+     * Present for a run of an ORG automation (AGL-3302), naming the
+     * organization that owns it. The steps run on this site exactly as a site
+     * action's do; what changes is that each is held to the org vocabulary as
+     * it runs, a wait enrolls under the org automation's own id, and the
+     * history row is filed under it.
+     */
+    orgAutomation?: {
+        orgId: string;
+    };
+}
 /**
  * What one Actions step did, for the run that holds it.
  *
@@ -128,6 +164,19 @@ export type ServerStepVerdict = {
 } | {
     kind: 'deferred';
 };
+/**
+ * Executes one action's SERVER steps in order, collecting per-step errors
+ * into the activity summary. Each step runs through {@link runServerStep}.
+ *
+ * An org automation's run comes through here too (AGL-3302): on the site the
+ * event happened on, against that site's run environment, so its email goes
+ * from that site and its CRM writes land in that site's facet.
+ *
+ * A `wait` step ENDS this call and hands the rest of the list to the job
+ * beat: everything after the wait belongs to a run that has not happened yet,
+ * so nothing below the wait may execute in this request.
+ */
+export declare function executeAction(env: ActionRunEnv, actionId: string, action: Pick<HostAction, 'name' | 'steps'>, event: string, payload: HostEventPayload, options?: ExecuteActionOptions): Promise<ActionRunEnding>;
 /** How a workflow run went, for whoever records or answers for it. */
 export interface WorkflowExecution {
     ending: ActionRunEnding;
@@ -182,6 +231,10 @@ export declare function executeWorkflow(env: ActionRunEnv, run: AutomationRun, w
  * optional filters over the payload, and executes each step list in
  * order. Never throws into the emitting request. Paid feature: the
  * `actions` flag gates and `actionRunsPerMonth` meters runs.
+ *
+ * The organization's automations placed on this site run here too
+ * (AGL-3302), after the site's own, on the same run environment — they run
+ * AS this site — and on the same meter.
  */
 export declare function runEventActions(hostId: string, event: string, payload?: HostEventPayload, depth?: number): Promise<HostActionAlert[]>;
 /**
@@ -195,8 +248,8 @@ export declare function runSingleAction(hostId: string, actionId: string, event:
 /**
  * Ends an enrollment its automation may no longer run, and says why in the
  * run history — the automation was deleted or switched off, or the plan that
- * carried it lapsed. Shared by both kinds of enrollment, so "stopped mid-wait"
- * reads the same for an action and a workflow.
+ * carried it lapsed. Shared by every kind of enrollment, so "stopped mid-wait"
+ * reads the same for an action, a workflow and an org automation.
  */
 export declare function stopFlowEnrollment(enrollment: FlowEnrollment, ref: FirebaseFirestore.DocumentReference, reason: string): Promise<'stopped'>;
 /**

package/src/lib/engine/run-event-actions.js

@@ -28,6 +28,8 @@ import { advanceFlowEnrollment, claimFlowEnrollment, deferFlowEnrollment, endFlo
 import { logCrmEmailActivity, prepareCrmEmailActivity, runCrmActionStep } from "./crm-action-steps.js";
 import { resolveDatasetDoc } from "@aglyn/tenant-runtime/resolve-dataset";
 import { resumeWorkflowEnrollment, runEventWorkflows } from "./run-event-workflows.js";
+import { ORG_AUTOMATION_RUN_TARGET, orgAutomationStepRefusal } from "../model/org-automations.js";
+import { findOrgAutomationsForEvent, resumeOrgAutomationEnrollment } from "./run-org-automations.js";
 import { isWorkflowActionStep, workflowActionStepRefusal, workflowHasActionSteps, workflowStepTypeLabel } from "./workflow-steps.js";
 /** Bounded fan-out per event, mirroring the workflow runner. */ const MAX_TRIGGERED_ACTIONS = 10;
 /**
@@ -755,16 +757,26 @@ async function datasetAppendRefusal(env, datasetRef) {
  * Executes one action's SERVER steps in order, collecting per-step errors
  * into the activity summary. Each step runs through {@link runServerStep}.
  *
+ * An org automation's run comes through here too (AGL-3302): on the site the
+ * event happened on, against that site's run environment, so its email goes
+ * from that site and its CRM writes land in that site's facet.
+ *
  * A `wait` step ENDS this call and hands the rest of the list to the job
  * beat: everything after the wait belongs to a run that has not happened yet,
  * so nothing below the wait may execute in this request.
- */ async function executeAction(env, actionId, action, event, payload, options = {}) {
-    var _action_name, _options_enrollmentRef, _ref, _options_steps, _options_startIndex, _action_name1;
+ */ export async function executeAction(env, actionId, action, event, payload, options = {}) {
+    var _options_orgAutomation, _action_name, _action_name1, _options_enrollmentRef, _ref, _options_steps, _options_startIndex, _action_name2;
     const { hostRef } = env;
-    const run = {
+    const orgRun = (_options_orgAutomation = options.orgAutomation) != null ? _options_orgAutomation : null;
+    const run = orgRun ? {
+        kind: 'orgAutomation',
+        id: actionId,
+        name: (_action_name = action.name) != null ? _action_name : '',
+        orgId: orgRun.orgId
+    } : {
         kind: 'action',
         id: actionId,
-        name: (_action_name = action.name) != null ? _action_name : ''
+        name: (_action_name1 = action.name) != null ? _action_name1 : ''
     };
     const enrollmentRef = (_options_enrollmentRef = options.enrollmentRef) != null ? _options_enrollmentRef : null;
     const steps = ((_ref = (_options_steps = options.steps) != null ? _options_steps : action.steps) != null ? _ref : []).slice(0, ACTION_MAX_STEPS);
@@ -785,6 +797,16 @@ async function datasetAppendRefusal(env, datasetRef) {
     }, payload);
     for(let index = startIndex; index < steps.length; index += 1){
         const step = steps[index];
+        /*
+     * An org automation runs its own vocabulary and nothing else. The save
+     * route refuses the rest, so this answers only a document written around
+     * it — and answers it before the step can reach this site's workflows or
+     * webhooks, which are not the organization's to call.
+     */ const refusal = orgRun ? orgAutomationStepRefusal(step) : null;
+        if (refusal) {
+            tally.errors.push(refusal);
+            continue;
+        }
         const verdict = await runServerStep(env, run, step, {
             index,
             steps,
@@ -802,7 +824,8 @@ async function datasetAppendRefusal(env, datasetRef) {
    * still ahead of this person, and a row per refused beat would bury the
    * runs that did something under a log of the ceiling working.
    */ if (ending === 'deferred') return ending;
-    const summary = stepErrors.length ? `Action ran on ${event} with errors: ${stepErrors.join('; ')}`.slice(0, 300) : ending === 'waiting' ? `Action is waiting, on ${event}` : `Action ran on ${event}`;
+    const noun = orgRun ? 'Org automation' : 'Action';
+    const summary = stepErrors.length ? `${noun} ran on ${event} with errors: ${stepErrors.join('; ')}`.slice(0, 300) : ending === 'waiting' ? `${noun} is waiting, on ${event}` : `${noun} ran on ${event}`;
     await hostRef.collection('activity').add({
         actorId: null,
         actorEmail: null,
@@ -816,9 +839,11 @@ async function datasetAppendRefusal(env, datasetRef) {
         trigger: event,
         summary: (outcomes.length ? outcomes.join(' · ') : 'Ran').slice(0, 300),
         target: {
-            type: 'workflow',
+            // An org automation's run is filed under its own type, so the site's
+            // run history can tell it from a site action sharing the feed.
+            type: orgRun ? ORG_AUTOMATION_RUN_TARGET : 'workflow',
             id: actionId,
-            name: (_action_name1 = action.name) != null ? _action_name1 : ''
+            name: (_action_name2 = action.name) != null ? _action_name2 : ''
         },
         createdAt: FieldValue.serverTimestamp()
     }).catch(()=>undefined);
@@ -946,7 +971,7 @@ async function datasetAppendRefusal(env, datasetRef) {
  * update there" twice is how the two drift into disagreeing about which
  * fields a waiting enrollment carries.
  */ async function suspendFlow(env, run, request) {
-    var _ref, _request_payload;
+    var _ref, _run_orgId, _ref1, _request_payload;
     var _request_payload1;
     const { step } = request;
     const minutes = step.type === 'wait' ? Number(step.delayMinutes) : step.type === 'waitForEvent' ? Number(step.timeoutMinutes) : 0;
@@ -975,6 +1000,9 @@ async function datasetAppendRefusal(env, datasetRef) {
         actionId: run.id
     }, run.kind === 'workflow' ? {
         automation: 'workflow'
+    } : {}, run.kind === 'orgAutomation' ? {
+        automation: 'org',
+        orgId: (_ref = (_run_orgId = run.orgId) != null ? _run_orgId : env.orgId) != null ? _ref : ''
     } : {}, {
         // The SNAPSHOT is the list this run is executing, which on a first run is
         // the automation's own — so one edited later cannot move this person's
@@ -985,7 +1013,7 @@ async function datasetAppendRefusal(env, datasetRef) {
                 ...request.steps
             ]
         },
-        email: String((_ref = (_request_payload1 = request.payload) == null ? void 0 : _request_payload1['email']) != null ? _ref : ''),
+        email: String((_ref1 = (_request_payload1 = request.payload) == null ? void 0 : _request_payload1['email']) != null ? _ref1 : ''),
         event: request.event,
         payload: (_request_payload = request.payload) != null ? _request_payload : {},
         nextStepIndex: request.nextStepIndex,
@@ -1024,7 +1052,7 @@ async function datasetAppendRefusal(env, datasetRef) {
  *
  * Never counts against `actionRunsPerMonth` — nothing executed, and
  * charging for a condition that said no would be its own bug.
- */ async function recordSkippedRun(hostRef, actionId, action, event) {
+ */ async function recordSkippedRun(hostRef, actionId, action, event, kind = 'action') {
     var _action_name;
     if (SKIP_LOG_EXCLUDED_EVENTS.has(event)) return;
     // `normalizeTriggerConditions`, not `trigger.conditions` — a pre-AGL-565
@@ -1038,12 +1066,12 @@ async function datasetAppendRefusal(env, datasetRef) {
     await hostRef.collection('activity').add({
         actorId: null,
         actorEmail: null,
-        action: `Action skipped on ${event}`,
+        action: `${kind === 'orgAutomation' ? 'Org automation' : 'Action'} skipped on ${event}`,
         result: 'skipped',
         trigger: event,
         summary: reason.slice(0, 300),
         target: {
-            type: 'workflow',
+            type: kind === 'orgAutomation' ? ORG_AUTOMATION_RUN_TARGET : 'workflow',
             id: actionId,
             name: (_action_name = action.name) != null ? _action_name : ''
         },
@@ -1056,6 +1084,10 @@ async function datasetAppendRefusal(env, datasetRef) {
  * optional filters over the payload, and executes each step list in
  * order. Never throws into the emitting request. Paid feature: the
  * `actions` flag gates and `actionRunsPerMonth` meters runs.
+ *
+ * The organization's automations placed on this site run here too
+ * (AGL-3302), after the site's own, on the same run environment — they run
+ * AS this site — and on the same meter.
  */ export async function runEventActions(hostId, event, payload = {}, depth = 0) {
     const alerts = [];
     if (depth > ACTION_MAX_EVENT_DEPTH) return alerts;
@@ -1073,18 +1105,39 @@ async function datasetAppendRefusal(env, datasetRef) {
         const hostRef = firestore.collection('hosts').doc(hostId);
         const triggered = await hostRef.collection('actions').where('trigger.event', '==', event).limit(MAX_TRIGGERED_ACTIONS).get();
         const actions = triggered.docs.filter((doc)=>!doc.get('deletedAt') && doc.get('enabled') !== false);
-        if (!actions.length) return alerts;
+        /*
+     * THE ORGANIZATION'S AUTOMATIONS placed on this site and not paused here.
+     *
+     * Asked only for an org trigger — a server event a person is the subject
+     * of — so a page view, a custom event and every on-page site event cost
+     * nothing more than they did. Never throws: an org lookup that fails runs
+     * this site's own actions exactly as before.
+     */ const placed = await findOrgAutomationsForEvent(hostId, event);
+        if (!actions.length && !placed) return alerts;
         const monthKey = new Date().toISOString().slice(0, 7);
         const runCounterRef = hostRef.collection('counters').doc('actionRuns');
         // Webhook steps take the higher `webhooks` gate (AGL-149); plan gates
         // ride the owning org's doc (AGL-238).
         let webhooksAllowed = true;
         let crmAllowed = true;
+        /*
+     * Whether each half fits under the month's allowance — all or nothing per
+     * half, as the site's own actions always were.
+     *
+     * The site's actions are asked first and on exactly the question they
+     * were always asked, so an organization placing automations on a site can
+     * never be what stops that site's own actions running. The org half is
+     * asked second, against what is left after the site's half, and both
+     * count on this site's one meter: an org automation's run is this site's
+     * run, and the usage card, the usage alerts and the COGS rollup read it
+     * there.
+     */ let runSite = false;
+        let runOrg = false;
         // Plan-less orgs resolve as free (AGL-247) — gates always run. Held for
         // the rest of the run so the dataset caps below cost no second read.
         const owner = await getOrgForHost(hostId);
         {
-            var _counterSnapshot_get;
+            var _counterSnapshot_get, _ref2;
             const org = owner == null ? void 0 : owner.org;
             if (!checkEntitlement(org, 'actions')) return alerts;
             webhooksAllowed = checkEntitlement(org, 'webhooks');
@@ -1092,7 +1145,16 @@ async function datasetAppendRefusal(env, datasetRef) {
             const limit = resolveOrgEntitlements(org).actionRunsPerMonth;
             const counterSnapshot = await runCounterRef.get();
             const used = Number((_counterSnapshot_get = counterSnapshot.get(monthKey)) != null ? _counterSnapshot_get : 0);
-            if (used + actions.length > limit) return alerts;
+            // Asked as "would it go over", the question this gate has always
+            // asked — so a counter that reads as no number refuses nothing, as
+            // before, rather than refusing everything.
+            runSite = actions.length > 0 && !(used + actions.length > limit);
+            /*
+       * Only for the organization the site belongs to NOW: the automations
+       * were found through the site's org, and a site that changed hands
+       * between the two reads runs none of its old organization's.
+       */ runOrg = Boolean(placed) && (placed == null ? void 0 : placed.orgId) === (owner == null ? void 0 : owner.orgId) && !(used + (runSite ? actions.length : 0) + ((_ref2 = placed == null ? void 0 : placed.docs.length) != null ? _ref2 : 0) > limit);
+            if (!runSite && !runOrg) return alerts;
         }
         const env = {
             hostId,
@@ -1108,7 +1170,7 @@ async function datasetAppendRefusal(env, datasetRef) {
             loadWorkflowContext: makeWorkflowContextLoader(hostRef)
         };
         let executed = 0;
-        for (const doc of actions){
+        for (const doc of runSite ? actions : []){
             var _action_trigger_filter, _action_trigger;
             const action = doc.data();
             const filter = (_action_trigger = action.trigger) == null ? void 0 : (_action_trigger_filter = _action_trigger.filter) == null ? void 0 : _action_trigger_filter.trim();
@@ -1138,6 +1200,36 @@ async function datasetAppendRefusal(env, datasetRef) {
             executed += 1;
             await executeAction(env, doc.id, action, event, payload);
         }
+        /*
+     * The org automations, judged by the same filter and conditions a site
+     * action is, skipped and recorded the same way, and run on this site.
+     */ for (const doc of runOrg && placed ? placed.docs : []){
+            var _ref3;
+            var _automation_trigger_filter, _automation_trigger;
+            const automation = doc.data();
+            const filter = (_automation_trigger = automation.trigger) == null ? void 0 : (_automation_trigger_filter = _automation_trigger.filter) == null ? void 0 : _automation_trigger_filter.trim();
+            if (filter) {
+                try {
+                    if (!evaluateExpression(filter, _extends({
+                        event
+                    }, payload))) continue;
+                } catch (unused) {
+                    continue; // A broken filter never fires.
+                }
+            }
+            if (!evaluateTriggerConditions(automation.trigger, _extends({
+                event
+            }, payload))) {
+                await recordSkippedRun(hostRef, doc.id, automation, event, 'orgAutomation');
+                continue;
+            }
+            executed += 1;
+            await executeAction(env, doc.id, automation, event, payload, {
+                orgAutomation: {
+                    orgId: (_ref3 = placed == null ? void 0 : placed.orgId) != null ? _ref3 : ''
+                }
+            });
+        }
         if (executed > 0) {
             await runCounterRef.set({
                 [monthKey]: FieldValue.increment(executed)
@@ -1223,8 +1315,8 @@ async function datasetAppendRefusal(env, datasetRef) {
 /**
  * Ends an enrollment its automation may no longer run, and says why in the
  * run history — the automation was deleted or switched off, or the plan that
- * carried it lapsed. Shared by both kinds of enrollment, so "stopped mid-wait"
- * reads the same for an action and a workflow.
+ * carried it lapsed. Shared by every kind of enrollment, so "stopped mid-wait"
+ * reads the same for an action, a workflow and an org automation.
  */ export async function stopFlowEnrollment(enrollment, ref, reason) {
     var _enrollment_actionName;
     const hostRef = firebaseAdmin.app().firestore().collection('hosts').doc(enrollment.hostId);
@@ -1237,7 +1329,7 @@ async function datasetAppendRefusal(env, datasetRef) {
         trigger: enrollment.event,
         summary: reason.slice(0, 300),
         target: {
-            type: 'workflow',
+            type: enrollment.automation === 'org' ? ORG_AUTOMATION_RUN_TARGET : 'workflow',
             id: enrollment.actionId,
             name: (_enrollment_actionName = enrollment.actionName) != null ? _enrollment_actionName : ''
         },
@@ -1266,6 +1358,14 @@ async function datasetAppendRefusal(env, datasetRef) {
             nowMs
         }));
     }
+    // An org automation's continues against the ORGANIZATION's document, which
+    // is its kill switch — deleted, switched off, taken off this site or paused
+    // here all stop it (AGL-3302).
+    if (enrollment.automation === 'org') {
+        return await resumeOrgAutomationEnrollment(enrollment, ref, _extends({}, options, {
+            nowMs
+        }));
+    }
     const hostId = enrollment.hostId;
     const firestore = firebaseAdmin.app().firestore();
     const hostRef = firestore.collection('hosts').doc(hostId);