@aglyn/tenant-data-admin 1.0.0-beta.196 → 1.0.0-beta.197

package/src/lib/server/consent-group-change.js

@@ -0,0 +1,1096 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * RUNNING A CONSENT GROUP CHANGE (AGL-3320) — the executor.
+ *
+ * `consent-group-change.ts` in `app-utils` decides WHAT a change requires;
+ * this carries it out, across as many invocations as it takes, without ever
+ * leaving a refusal unhonored in between.
+ *
+ * ## The order is the safety argument
+ *
+ *  1. START — one transaction on the org document: the stored declaration is
+ *     the one the editor rendered, and no other change is in flight. It sets
+ *     the marker `consentGroupsChange` and creates the job document.
+ *  2. CARRY — every carry of the plan through the three platform stores
+ *     (`consent-group-carry.ts`), then every participant's carry phase.
+ *  3. CATCH UP — everything filed since the carry began, again.
+ *  4. DECLARE — one transaction: the marker still names this change in its
+ *     carry phase and the stored declaration is still the one the job
+ *     started from. Only then is the new declaration written.
+ *  5. CATCH UP — once more, for whatever raced the flip.
+ *  6. RE-HOME — every participant's holder records.
+ *  7. SWEEP — once the sweep delay has passed, the whole carry and every
+ *     participant's sweep, idempotently.
+ *  8. DONE — the marker is cleared.
+ *
+ * The flip cannot happen before every carry and both catch-up passes are
+ * done, because the steps run strictly in order and `declare` is only ever
+ * reached from a finished `catch-up-pre`. Until the flip the declaration in
+ * force is the old one, so a change that stalls or is canceled before it
+ * has changed nothing anybody can observe — except refusals honored on more
+ * sites, which is the safe direction. A rename moves nothing, and runs the
+ * declare and finish alone.
+ *
+ * ## One invocation at a time, and any invocation may finish it
+ *
+ * The console's progress panel calls `continue` while it is open, and the
+ * cron backstop calls every fifteen minutes. Each claims a LEASE on the job
+ * by transaction and renews it on every unit it saves; a lease that lapses
+ * (a process that died) is simply claimed by the next caller. A unit is one
+ * page of one store, or one participant call, and every unit is idempotent,
+ * so a unit re-run after a crash writes nothing it already wrote.
+ *
+ * ## A failure is retried, and five in a row are shown
+ *
+ * A unit that throws releases the lease and counts a failure against the job;
+ * the next invocation retries it from its cursor. Five consecutive failures
+ * mark the job STALLED — the activity log says so once, and the panel shows
+ * the error with a retry — and the cron keeps trying. A participant's throw
+ * is one of these: the change never flips past a participant that could not
+ * carry its refusals (see `plugin-consent-group-change.ts`).
+ */ import { CONSENT_GROUP_CHANGE_STEPS, CONSENT_GROUP_CHANGES_COLLECTION, CONSENT_GROUP_RENAME_STEPS, CONSENT_GROUP_SWEEP_DELAY_MS, CONSENT_GROUPS_CHANGE_FIELD, consentGroupChangePhaseOf, consentGroupDisclosureChanges, consentGroupsFingerprint, describeConsentGroupChangeLine, discardedConsentGroupIds, estimateConsentGroupChange, orgSiteIds, planConsentGroupChange, readConsentGroupsChange, validateConsentGroupDeclaration } from "@aglyn/aglyn/app-utils/consent-group-change";
+import { CONSENT_GROUPS_FIELD, consentGroupsAwaitConfirmation, readConsentGroups } from "@aglyn/aglyn/app-utils/consent-groups";
+import { createResourceUid } from "@aglyn/aglyn/app-utils/create-resource-uid";
+import { DEFAULT_EMAIL_TOPICS, TOPIC_OPT_OUTS_SUBCOLLECTION } from "@aglyn/aglyn/app-utils/email-topics";
+import { resolveMarketingConsentPolicy } from "@aglyn/aglyn/app-utils/marketing-consent";
+import { isOrgWideMember } from "@aglyn/aglyn/app-utils/organizations";
+import { listPluginConsentGroupParticipants, previewPluginConsentGroupChange } from "@aglyn/aglyn/plugin-manager/plugin-consent-group-change";
+import { FieldValue } from "firebase-admin/firestore";
+import { CONSENT_GROUP_CARRY_STORES, CONSENT_GROUP_CARRY_SUBCOLLECTIONS, carryConsentGroupRefusals } from "./consent-group-carry.js";
+import firebaseAdmin from "./firebase-admin.js";
+import { getLockdownVerdict } from "./lockdown.js";
+import { logOrgActivity } from "./organizations.js";
+/** How long a claimed job stays claimed without a renewal. */ export const CONSENT_GROUP_CHANGE_LEASE_MS = 90000;
+/** Consecutive failed units before a job is shown as stalled. */ export const CONSENT_GROUP_CHANGE_STALL_AFTER = 5;
+/**
+ * How far before the carry began a catch-up reads. A refusal filed in the
+ * seconds the carry's first page was being read, with a clock a little
+ * behind, is inside it.
+ */ const CATCH_UP_OVERLAP_MS = 5 * 60000;
+/** Left before a deadline for the last save. */ const DEADLINE_SAFETY_MS = 5000;
+/** The phases the cron looks for a change in. */ const RUNNING_PHASES = [
+    'carry',
+    'rehome',
+    'sweep'
+];
+function contextOf(input) {
+    var _input_firestore, _input_log, _input_now, _input_lockedOut;
+    return {
+        firestore: (_input_firestore = input.firestore) != null ? _input_firestore : firebaseAdmin.app().firestore(),
+        log: (_input_log = input.log) != null ? _input_log : logOrgActivity,
+        now: (_input_now = input.now) != null ? _input_now : Date.now,
+        lockedOut: (_input_lockedOut = input.lockedOut) != null ? _input_lockedOut : async (org, uid)=>await getLockdownVerdict({
+                org: org,
+                uid,
+                intent: 'write'
+            }) !== null
+    };
+}
+const NOT_FOUND = {
+    ok: false,
+    status: 404,
+    body: {
+        error: 'No such consent group change'
+    }
+};
+/** A caller whose lease was taken, or whose job was canceled, under it. */ let LeaseLost = class LeaseLost extends Error {
+};
+const orgDoc = (ctx, orgId)=>ctx.firestore.collection('orgs').doc(orgId);
+const jobDoc = (ctx, orgId, changeId)=>orgDoc(ctx, orgId).collection(CONSENT_GROUP_CHANGES_COLLECTION).doc(changeId);
+/** The job as the plan the participants and the carries read. */ function planOf(job) {
+    return _extends({}, job.plan, {
+        before: job.before,
+        after: job.after
+    });
+}
+/** An error as the job records it: bounded, and with no address in it. */ function sanitizeError(error) {
+    const message = error instanceof Error ? error.message : String(error != null ? error : 'Unknown error');
+    return message.replace(/[^\s@]+@[^\s@]+/g, '[address]').slice(0, 300) || 'Unknown error';
+}
+export function consentGroupChangeStatus(job, nowMs = Date.now()) {
+    var _job_declaredAtMs, _job_failures, _job_lastError, _ref, _job_plugins;
+    var _job_sitesReceiving;
+    const declaredAtMs = (_job_declaredAtMs = job.declaredAtMs) != null ? _job_declaredAtMs : null;
+    const index = job.steps.indexOf(job.step);
+    return {
+        changeId: job.changeId,
+        phase: job.phase,
+        done: job.status !== 'running',
+        progress: {
+            status: job.status,
+            step: job.step,
+            stepIndex: index >= 0 ? index + 1 : job.steps.length,
+            stepCount: job.steps.length,
+            declaredAtMs,
+            sweepAtMs: declaredAtMs !== null && !job.plan.renameOnly ? declaredAtMs + CONSENT_GROUP_SWEEP_DELAY_MS : null,
+            stalled: job.stalled === true,
+            failures: (_job_failures = job.failures) != null ? _job_failures : 0,
+            lastError: (_job_lastError = job.lastError) != null ? _job_lastError : null,
+            leaseUntilMs: job.lease && job.lease.untilMs > nowMs ? job.lease.untilMs : null,
+            counts: _extends({}, job.counts),
+            sitesReceiving: (_ref = (_job_sitesReceiving = job.sitesReceiving) == null ? void 0 : _job_sitesReceiving.length) != null ? _ref : 0,
+            plugins: (_job_plugins = job.plugins) != null ? _job_plugins : {}
+        }
+    };
+}
+function prepare(org, expected, groups) {
+    const marker = readConsentGroupsChange(org);
+    if (marker) {
+        return {
+            ok: false,
+            status: 409,
+            body: {
+                error: 'A consent group change is still finishing',
+                changeId: marker.changeId,
+                phase: marker.phase
+            }
+        };
+    }
+    const raw = org[CONSENT_GROUPS_FIELD];
+    if (consentGroupsFingerprint(raw) !== consentGroupsFingerprint(expected)) {
+        return {
+            ok: false,
+            status: 409,
+            body: {
+                error: 'Someone else changed consent groups while you were editing',
+                current: raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : null
+            }
+        };
+    }
+    const before = readConsentGroups(org);
+    const siteIds = orgSiteIds(org);
+    const validation = validateConsentGroupDeclaration({
+        groups,
+        before,
+        siteIds,
+        reserved: raw && typeof raw === 'object' && !Array.isArray(raw) ? Object.keys(raw) : []
+    });
+    if (!validation.ok) {
+        return {
+            ok: false,
+            status: 400,
+            body: {
+                error: 'Those consent groups cannot be saved',
+                errors: validation.errors
+            }
+        };
+    }
+    const after = validation.after;
+    return {
+        org,
+        before,
+        after,
+        plan: planConsentGroupChange(before, after, {
+            siteIds
+        }),
+        siteIds
+    };
+}
+const isRefusal = (value)=>Boolean(value && typeof value === 'object' && value.ok === false);
+/** Every site a plan names, for the names its lines are written with. */ function plannedSites(plan) {
+    return [
+        ...new Set([
+            ...plan.hostIds,
+            ...Object.values(plan.before).flatMap((group)=>group.hostIds),
+            ...Object.values(plan.after).flatMap((group)=>group.hostIds)
+        ])
+    ];
+}
+/** What the console calls each site: its name, its subdomain, or its id. */ async function siteNamesFor(ctx, hostIds) {
+    if (!hostIds.length) return {};
+    const hosts = ctx.firestore.collection('hosts');
+    const snapshots = await ctx.firestore.getAll(...hostIds.map((id)=>hosts.doc(id)));
+    const names = {};
+    snapshots.forEach((snapshot, index)=>{
+        const id = hostIds[index];
+        names[id] = String(snapshot.get('name') || snapshot.get('subdomain') || id);
+    });
+    return names;
+}
+const describeLines = (lines, names)=>lines.map((line)=>describeConsentGroupChangeLine(line, (hostId)=>{
+            var _names_hostId;
+            return (_names_hostId = names[hostId]) != null ? _names_hostId : hostId;
+        }));
+/*==========================================
+ * THE PREVIEW
+ *=========================================*/ async function countOf(query) {
+    const snapshot = await query.count().get();
+    return Number(snapshot.data().count) || 0;
+}
+/**
+ * What a change would do, counted and worded, writing nothing.
+ *
+ * Refused exactly as `apply` would be — a change in flight, a stale
+ * `expected`, an invalid declaration — so the review step never shows a
+ * change the next click cannot make.
+ */ export async function previewConsentGroupChange(input) {
+    var _input_org;
+    const ctx = contextOf(input);
+    const org = (_input_org = input.org) != null ? _input_org : (await orgDoc(ctx, input.orgId).get()).data();
+    if (!org) return {
+        ok: false,
+        status: 404,
+        body: {
+            error: 'No such workspace'
+        }
+    };
+    const prepared = prepare(org, input.expected, input.groups);
+    if (isRefusal(prepared)) return prepared;
+    const { plan, before, after } = prepared;
+    const db = ctx.firestore;
+    const cache = new Map();
+    const cached = (key, query)=>{
+        let pending = cache.get(key);
+        if (!pending) {
+            pending = countOf(query());
+            cache.set(key, pending);
+        }
+        return pending;
+    };
+    const store = (hostId, name)=>db.collection('hosts').doc(hostId).collection(CONSENT_GROUP_CARRY_SUBCOLLECTIONS[name]);
+    const suppressions = (hostId)=>cached(`s:${hostId}`, ()=>store(hostId, 'siteSuppressions'));
+    const optOuts = (hostId)=>cached(`t:${hostId}`, ()=>store(hostId, 'topicOptOuts'));
+    const paces = (hostId)=>cached(`p:${hostId}`, ()=>store(hostId, 'paces').where('cadence', '!=', null));
+    const carries = await Promise.all(plan.carries.map(async (carry)=>({
+            toHostId: carry.toHostId,
+            fromHostId: carry.fromHostId,
+            siteSuppressions: await suppressions(carry.fromHostId),
+            topicOptOuts: await optOuts(carry.fromHostId),
+            paces: await paces(carry.fromHostId)
+        })));
+    const membersIn = (declaration, hostId)=>{
+        var _ref;
+        var _Object_values_find;
+        return (_ref = (_Object_values_find = Object.values(declaration).find((group)=>group.hostIds.includes(hostId))) == null ? void 0 : _Object_values_find.hostIds) != null ? _ref : [
+            hostId
+        ];
+    };
+    const joining = [];
+    for (const hostId of [
+        ...new Set(Object.values(after).flatMap((group)=>group.hostIds))
+    ].sort()){
+        const had = new Set(membersIn(before, hostId));
+        const siblings = membersIn(after, hostId).filter((id)=>id !== hostId && !had.has(id));
+        if (siblings.length) joining.push({
+            hostId,
+            siblings
+        });
+    }
+    const inherited = await Promise.all(joining.map(async ({ hostId, siblings })=>{
+        let refusals = 0;
+        for (const sibling of siblings){
+            refusals += await suppressions(sibling) + await optOuts(sibling);
+        }
+        return {
+            hostId,
+            refusals
+        };
+    }));
+    /*
+   * A pending confirmation holds a sibling's mail only with the switch on,
+   * so only then does a separation release anything. Counted over the
+   * built-in streams: the catalog of an organization's own streams belongs to
+   * the Email plugin, and a stream it added is not counted here.
+   */ const pendingHolds = [];
+    if (consentGroupsAwaitConfirmation(org)) {
+        const released = new Map();
+        for (const carry of plan.carries){
+            var _released_get;
+            released.set(carry.toHostId, [
+                ...(_released_get = released.get(carry.toHostId)) != null ? _released_get : [],
+                carry.fromHostId
+            ]);
+        }
+        for (const [hostId, releasedHostIds] of [
+            ...released.entries()
+        ].sort()){
+            for (const topic of DEFAULT_EMAIL_TOPICS){
+                const count = await countOf(db.collection('hosts').doc(hostId).collection(TOPIC_OPT_OUTS_SUBCOLLECTION).where(`topics.${topic.id}.confirmedAt`, '==', null));
+                if (count > 0) pendingHolds.push({
+                    hostId,
+                    topicId: topic.id,
+                    count,
+                    releasedHostIds
+                });
+            }
+        }
+    }
+    const changedGroups = Object.entries(after).filter(([id, group])=>{
+        const was = before[id];
+        return !was || was.hostIds.join('\n') !== group.hostIds.join('\n');
+    }).map(([, group])=>group.hostIds);
+    let partialAccessMembers = 0;
+    if (changedGroups.length) {
+        const members = await orgDoc(ctx, input.orgId).collection('members').get();
+        for (const member of members.docs){
+            var _data_hostAccess;
+            const data = member.data();
+            if (isOrgWideMember(data)) continue;
+            const reach = new Set(Object.keys((_data_hostAccess = data['hostAccess']) != null ? _data_hostAccess : {}));
+            if (changedGroups.some((hostIds)=>hostIds.some((id)=>reach.has(id)) && !hostIds.every((id)=>reach.has(id)))) {
+                partialAccessMembers += 1;
+            }
+        }
+    }
+    const policy = resolveMarketingConsentPolicy(org['marketingConsentPolicy']);
+    const forwardPolicyWarning = policy.mode === 'forward' && joining.length ? {
+        hostIds: joining.map((entry)=>entry.hostId),
+        enforceFromMs: policy.enforceFromMs
+    } : null;
+    const participants = await previewPluginConsentGroupChange({
+        orgId: input.orgId,
+        plan
+    });
+    const names = await siteNamesFor(ctx, plannedSites(plan));
+    const texts = describeLines(plan.lines, names);
+    const documents = carries.reduce((total, carry)=>total + carry.siteSuppressions + carry.topicOptOuts + carry.paces, 0) + participants.reduce((total, entry)=>{
+        var _entry_lines;
+        return total + ((_entry_lines = entry.lines) != null ? _entry_lines : []).reduce((sum, line)=>{
+            var _line_count;
+            return sum + ((_line_count = line.count) != null ? _line_count : 0);
+        }, 0);
+    }, 0);
+    return {
+        ok: true,
+        preview: {
+            before,
+            after,
+            discarded: discardedConsentGroupIds(org),
+            lines: plan.lines.map((line, index)=>_extends({}, line, {
+                    text: texts[index]
+                })),
+            disclosures: consentGroupDisclosureChanges(before, after),
+            carries,
+            inherited,
+            pendingHolds,
+            partialAccessMembers,
+            forwardPolicyWarning,
+            participants,
+            capturesDisclosing: [
+                'form'
+            ],
+            estimate: estimateConsentGroupChange(plan, documents)
+        }
+    };
+}
+/*==========================================
+ * STARTING
+ *=========================================*/ /**
+ * Starts a change: the org marker and the job, in one transaction that
+ * refuses a change in flight, a stale `expected` and an invalid declaration.
+ * Writes nothing else — the caller advances it.
+ */ export async function startConsentGroupChange(input) {
+    const ctx = contextOf(input);
+    const orgRef = orgDoc(ctx, input.orgId);
+    const snapshot = await orgRef.get();
+    if (!snapshot.exists) return {
+        ok: false,
+        status: 404,
+        body: {
+            error: 'No such workspace'
+        }
+    };
+    const outside = prepare(snapshot.data(), input.expected, input.groups);
+    if (isRefusal(outside)) return outside;
+    // Names are words for the log, read once and outside the transaction.
+    const names = await siteNamesFor(ctx, plannedSites(outside.plan));
+    const participants = listPluginConsentGroupParticipants().map((entry)=>entry.pluginId);
+    const changeId = createResourceUid();
+    const jobRef = jobDoc(ctx, input.orgId, changeId);
+    const nowMs = ctx.now();
+    const started = await ctx.firestore.runTransaction(async (transaction)=>{
+        var _input_actor_uid, _input_actor_email;
+        const current = await transaction.get(orgRef);
+        if (!current.exists) {
+            return {
+                ok: false,
+                status: 404,
+                body: {
+                    error: 'No such workspace'
+                }
+            };
+        }
+        const prepared = prepare(current.data(), input.expected, input.groups);
+        if (isRefusal(prepared)) return prepared;
+        const { plan, before, after, org } = prepared;
+        const steps = plan.renameOnly ? [
+            ...CONSENT_GROUP_RENAME_STEPS
+        ] : [
+            ...CONSENT_GROUP_CHANGE_STEPS
+        ];
+        const job = {
+            changeId,
+            orgId: input.orgId,
+            status: 'running',
+            step: steps[0],
+            phase: 'carry',
+            steps,
+            beforeFingerprint: consentGroupsFingerprint(org[CONSENT_GROUPS_FIELD]),
+            before,
+            after,
+            plan: {
+                carries: plan.carries,
+                flows: plan.flows,
+                lines: plan.lines,
+                hostIds: plan.hostIds,
+                renameOnly: plan.renameOnly
+            },
+            lines: describeLines(plan.lines, names),
+            siteNames: names,
+            participants: plan.renameOnly ? [] : participants,
+            units: {},
+            counts: {
+                siteSuppressions: 0,
+                topicOptOuts: 0,
+                paces: 0
+            },
+            sitesReceiving: [],
+            plugins: {},
+            lease: null,
+            failures: 0,
+            stalled: false,
+            lastError: null,
+            actor: {
+                uid: (_input_actor_uid = input.actor.uid) != null ? _input_actor_uid : null,
+                email: (_input_actor_email = input.actor.email) != null ? _input_actor_email : null
+            },
+            startedAtMs: nowMs,
+            carryStartedAtMs: nowMs,
+            declaredAtMs: null,
+            finishedAtMs: null,
+            canceledAtMs: null
+        };
+        const marker = {
+            changeId,
+            phase: 'carry',
+            hostIds: plan.hostIds,
+            startedAtMs: nowMs
+        };
+        transaction.update(orgRef, {
+            [CONSENT_GROUPS_CHANGE_FIELD]: marker,
+            updatedAt: FieldValue.serverTimestamp()
+        });
+        transaction.create(jobRef, _extends({}, job, {
+            createdAt: FieldValue.serverTimestamp(),
+            updatedAt: FieldValue.serverTimestamp()
+        }));
+        return {
+            ok: true,
+            job
+        };
+    });
+    if (isRefusal(started)) return started;
+    const { job } = started;
+    await ctx.log(input.orgId, {
+        uid: job.actor.uid,
+        email: job.actor.email
+    }, `Started a consent group change: ${job.lines.join('; ')}`, {
+        type: 'org',
+        id: input.orgId
+    });
+    return {
+        ok: true,
+        changeId,
+        job
+    };
+}
+/** The current step's units, in the order they run. */ function unitsOf(job) {
+    const carries = (sinceMs)=>job.plan.carries.flatMap((_carry, carryIndex)=>CONSENT_GROUP_CARRY_STORES.map((store)=>({
+                    kind: 'carry',
+                    key: `c${carryIndex}:${store}`,
+                    carryIndex,
+                    store,
+                    sinceMs
+                })));
+    const participants = (phase)=>job.participants.map((pluginId)=>({
+                kind: 'participant',
+                key: `p:${pluginId}`,
+                pluginId,
+                phase
+            }));
+    const since = job.carryStartedAtMs - CATCH_UP_OVERLAP_MS;
+    switch(job.step){
+        case 'carry':
+            return [
+                ...carries(null),
+                ...participants('carry')
+            ];
+        case 'catch-up-pre':
+        case 'catch-up-post':
+            return [
+                ...carries(since),
+                ...participants('carry')
+            ];
+        case 'rehome':
+            return participants('rehome');
+        case 'sweep':
+            return [
+                ...carries(null),
+                ...participants('sweep')
+            ];
+        default:
+            return [];
+    }
+}
+function jobFrom(snapshot) {
+    return snapshot.exists ? snapshot.data() : null;
+}
+/**
+ * Saves a unit's result, renewing the lease — only while the job is still
+ * running and still this caller's.
+ */ async function save(ctx, jobRef, owner, fields, extra) {
+    return ctx.firestore.runTransaction(async (transaction)=>{
+        var _job_lease;
+        const job = jobFrom(await transaction.get(jobRef));
+        if (!job || job.status !== 'running' || ((_job_lease = job.lease) == null ? void 0 : _job_lease.owner) !== owner) throw new LeaseLost();
+        if (extra) await extra(transaction, job);
+        const next = _extends({}, fields, {
+            lease: {
+                owner,
+                untilMs: ctx.now() + CONSENT_GROUP_CHANGE_LEASE_MS
+            },
+            failures: 0,
+            stalled: false,
+            lastError: null
+        });
+        transaction.update(jobRef, _extends({}, next, {
+            updatedAt: FieldValue.serverTimestamp()
+        }));
+        return _extends({}, job, next);
+    });
+}
+function addCounts(base, more) {
+    const out = _extends({}, base != null ? base : {});
+    for (const [key, value] of Object.entries(more)){
+        var _out_key;
+        if (typeof value === 'number' && Number.isFinite(value)) out[key] = ((_out_key = out[key]) != null ? _out_key : 0) + value;
+    }
+    return out;
+}
+async function runUnit(ctx, jobRef, job, owner, unit, deadlineMs) {
+    var _job_units_unit_key, _result_cursor, _result_counts;
+    const state = (_job_units_unit_key = job.units[unit.key]) != null ? _job_units_unit_key : {
+        cursor: null,
+        done: false
+    };
+    if (unit.kind === 'carry') {
+        var _job_counts_unit_store;
+        const carry = job.plan.carries[unit.carryIndex];
+        const page = await carryConsentGroupRefusals({
+            firestore: ctx.firestore,
+            store: unit.store,
+            carry,
+            changeId: job.changeId,
+            cursor: state.cursor,
+            sinceMs: unit.sinceMs
+        });
+        const counts = _extends({}, job.counts, {
+            [unit.store]: ((_job_counts_unit_store = job.counts[unit.store]) != null ? _job_counts_unit_store : 0) + page.written
+        });
+        const sitesReceiving = page.written > 0 && !job.sitesReceiving.includes(carry.toHostId) ? [
+            ...job.sitesReceiving,
+            carry.toHostId
+        ] : job.sitesReceiving;
+        return save(ctx, jobRef, owner, {
+            units: _extends({}, job.units, {
+                [unit.key]: {
+                    cursor: page.cursor,
+                    done: page.done
+                }
+            }),
+            counts,
+            sitesReceiving
+        });
+    }
+    const participant = participantFor(unit.pluginId);
+    const result = await participant.run({
+        orgId: job.orgId,
+        changeId: job.changeId,
+        plan: planOf(job),
+        phase: unit.phase,
+        cursor: state.cursor,
+        deadlineMs: deadlineMs - DEADLINE_SAFETY_MS,
+        dryRun: false
+    });
+    return save(ctx, jobRef, owner, {
+        units: _extends({}, job.units, {
+            [unit.key]: {
+                cursor: (_result_cursor = result.cursor) != null ? _result_cursor : null,
+                done: result.done === true
+            }
+        }),
+        plugins: _extends({}, job.plugins, {
+            [unit.pluginId]: addCounts(job.plugins[unit.pluginId], (_result_counts = result.counts) != null ? _result_counts : {})
+        })
+    });
+}
+function participantFor(pluginId) {
+    const entry = listPluginConsentGroupParticipants().find((candidate)=>candidate.pluginId === pluginId);
+    if (!entry) {
+        // The change started with this participant; running on without it would
+        // skip its share. Another process — one whose declarations registered it —
+        // picks the job up.
+        throw new Error(`The ${pluginId} plugin's part of this change is not available here`);
+    }
+    return entry.participant;
+}
+/** Moves the job to the step after its current one. */ async function nextStep(ctx, orgId, jobRef, job, owner) {
+    var _job_steps_;
+    const next = (_job_steps_ = job.steps[job.steps.indexOf(job.step) + 1]) != null ? _job_steps_ : 'finish';
+    const phase = consentGroupChangePhaseOf(next);
+    if (phase === job.phase) return save(ctx, jobRef, owner, {
+        step: next,
+        units: {}
+    });
+    // Entering the sweep: the marker says so, for the readers that hold off
+    // while holder records may still be moving.
+    const orgRef = orgDoc(ctx, orgId);
+    return save(ctx, jobRef, owner, {
+        step: next,
+        units: {},
+        phase
+    }, async (transaction)=>{
+        const marker = readConsentGroupsChange((await transaction.get(orgRef)).data());
+        if ((marker == null ? void 0 : marker.changeId) === job.changeId) {
+            transaction.update(orgRef, {
+                [`${CONSENT_GROUPS_CHANGE_FIELD}.phase`]: phase
+            });
+        }
+    });
+}
+/**
+ * THE FLIP — the one write of `consentGroups` anywhere in the platform.
+ *
+ * The marker must still name this change in its carry phase and the stored
+ * declaration must be the one the job started from; otherwise nothing is
+ * written and the unit fails. `update`, not a merge, so a removed group's id
+ * vanishes with it; an empty declaration deletes the field.
+ */ async function declare(ctx, jobRef, job, owner) {
+    const orgRef = orgDoc(ctx, job.orgId);
+    const nowMs = ctx.now();
+    const renameOnly = job.plan.renameOnly;
+    const declared = await save(ctx, jobRef, owner, renameOnly ? {
+        step: 'finish',
+        status: 'done',
+        phase: 'done',
+        declaredAtMs: nowMs,
+        finishedAtMs: nowMs,
+        units: {}
+    } : {
+        step: 'catch-up-post',
+        phase: 'rehome',
+        declaredAtMs: nowMs,
+        units: {}
+    }, async (transaction)=>{
+        const org = (await transaction.get(orgRef)).data();
+        const marker = readConsentGroupsChange(org);
+        if (!org || (marker == null ? void 0 : marker.changeId) !== job.changeId || marker.phase !== 'carry') {
+            throw new Error('The change no longer holds the organization, so the new groups were not saved');
+        }
+        if (consentGroupsFingerprint(org[CONSENT_GROUPS_FIELD]) !== job.beforeFingerprint) {
+            throw new Error('The consent groups changed outside this change, so the new groups were not saved');
+        }
+        transaction.update(orgRef, {
+            [CONSENT_GROUPS_FIELD]: Object.keys(job.after).length ? job.after : FieldValue.delete(),
+            [CONSENT_GROUPS_CHANGE_FIELD]: renameOnly ? FieldValue.delete() : _extends({}, marker, {
+                phase: 'rehome',
+                declaredAtMs: nowMs
+            }),
+            updatedAt: FieldValue.serverTimestamp()
+        });
+    });
+    const finished = renameOnly ? _extends({}, declared, {
+        lease: null
+    }) : declared;
+    if (renameOnly) await jobRef.update({
+        lease: null
+    });
+    for (const line of job.lines){
+        await ctx.log(job.orgId, job.actor, line, {
+            type: 'org',
+            id: job.orgId
+        });
+    }
+    if (renameOnly) {
+        await ctx.log(job.orgId, job.actor, 'Finished a consent group change', {
+            type: 'org',
+            id: job.orgId
+        });
+    }
+    return finished;
+}
+/** The "Finished" line: the carries' totals, then each participant's clause. */ function finishedLine(job) {
+    const copied = job.counts.siteSuppressions + job.counts.topicOptOuts + job.counts.paces;
+    const sites = job.sitesReceiving.length;
+    const clauses = [
+        `${copied} ${copied === 1 ? 'opt-out' : 'opt-outs'} copied to ${sites} ${sites === 1 ? 'site' : 'sites'}`
+    ];
+    for (const pluginId of job.participants){
+        var _job_plugins_pluginId;
+        var _entry_participant_summarize;
+        const entry = listPluginConsentGroupParticipants().find((candidate)=>candidate.pluginId === pluginId);
+        const clause = entry == null ? void 0 : (_entry_participant_summarize = entry.participant.summarize) == null ? void 0 : _entry_participant_summarize.call(entry.participant, (_job_plugins_pluginId = job.plugins[pluginId]) != null ? _job_plugins_pluginId : {});
+        if (clause) clauses.push(clause);
+    }
+    return `Finished a consent group change: ${clauses.join('; ')}`;
+}
+async function finish(ctx, jobRef, job, owner) {
+    const orgRef = orgDoc(ctx, job.orgId);
+    const nowMs = ctx.now();
+    const done = await save(ctx, jobRef, owner, {
+        status: 'done',
+        phase: 'done',
+        step: 'finish',
+        finishedAtMs: nowMs,
+        units: {}
+    }, async (transaction)=>{
+        const marker = readConsentGroupsChange((await transaction.get(orgRef)).data());
+        if ((marker == null ? void 0 : marker.changeId) === job.changeId) {
+            transaction.update(orgRef, {
+                [CONSENT_GROUPS_CHANGE_FIELD]: FieldValue.delete(),
+                updatedAt: FieldValue.serverTimestamp()
+            });
+        }
+    });
+    await jobRef.update({
+        lease: null
+    });
+    await ctx.log(job.orgId, job.actor, finishedLine(done), {
+        type: 'org',
+        id: job.orgId
+    });
+    return _extends({}, done, {
+        lease: null
+    });
+}
+/**
+ * One unit of work, or nothing when the job is waiting for its sweep.
+ */ async function advanceOnce(ctx, jobRef, job, owner, deadlineMs) {
+    var _ref, _ref1;
+    var _job_units_unit_key;
+    if (job.step === 'declare') return {
+        job: await declare(ctx, jobRef, job, owner),
+        idle: false
+    };
+    if (job.step === 'finish') return {
+        job: await finish(ctx, jobRef, job, owner),
+        idle: false
+    };
+    if (job.step === 'sweep-wait') {
+        var _job_declaredAtMs;
+        if (ctx.now() < ((_job_declaredAtMs = job.declaredAtMs) != null ? _job_declaredAtMs : 0) + CONSENT_GROUP_SWEEP_DELAY_MS) return {
+            job,
+            idle: true
+        };
+        return {
+            job: await nextStep(ctx, job.orgId, jobRef, job, owner),
+            idle: false
+        };
+    }
+    const unit = unitsOf(job).find((candidate)=>{
+        var _job_units_candidate_key;
+        return !((_job_units_candidate_key = job.units[candidate.key]) == null ? void 0 : _job_units_candidate_key.done);
+    });
+    if (!unit) return {
+        job: await nextStep(ctx, job.orgId, jobRef, job, owner),
+        idle: false
+    };
+    const before = (_ref = (_job_units_unit_key = job.units[unit.key]) == null ? void 0 : _job_units_unit_key.cursor) != null ? _ref : null;
+    const after = await runUnit(ctx, jobRef, job, owner, unit, deadlineMs);
+    const state = after.units[unit.key];
+    // A participant that stopped where it started — out of time before its
+    // first page — has nothing more to give this invocation.
+    return {
+        job: after,
+        idle: unit.kind === 'participant' && !(state == null ? void 0 : state.done) && ((_ref1 = state == null ? void 0 : state.cursor) != null ? _ref1 : null) === before
+    };
+}
+/** Claims the lease, or answers why not. `null` for a job that does not exist. */ async function claim(ctx, jobRef, owner) {
+    return ctx.firestore.runTransaction(async (transaction)=>{
+        const job = jobFrom(await transaction.get(jobRef));
+        if (!job) return null;
+        const nowMs = ctx.now();
+        if (job.status !== 'running') return {
+            job,
+            mine: false
+        };
+        if (job.lease && job.lease.untilMs > nowMs && job.lease.owner !== owner) return {
+            job,
+            mine: false
+        };
+        const lease = {
+            owner,
+            untilMs: nowMs + CONSENT_GROUP_CHANGE_LEASE_MS
+        };
+        transaction.update(jobRef, {
+            lease
+        });
+        return {
+            job: _extends({}, job, {
+                lease
+            }),
+            mine: true
+        };
+    });
+}
+async function release(ctx, jobRef, owner) {
+    return ctx.firestore.runTransaction(async (transaction)=>{
+        var _job_lease;
+        const job = jobFrom(await transaction.get(jobRef));
+        if (!job) return null;
+        if (((_job_lease = job.lease) == null ? void 0 : _job_lease.owner) !== owner) return job;
+        transaction.update(jobRef, {
+            lease: null
+        });
+        return _extends({}, job, {
+            lease: null
+        });
+    });
+}
+/** Counts a failed unit against the job, and says so once when it stalls. */ async function recordFailure(ctx, jobRef, owner, error) {
+    const lastError = sanitizeError(error);
+    const outcome = await ctx.firestore.runTransaction(async (transaction)=>{
+        var _job_failures;
+        var _job_lease;
+        const job = jobFrom(await transaction.get(jobRef));
+        if (!job) return null;
+        if (((_job_lease = job.lease) == null ? void 0 : _job_lease.owner) !== owner) return {
+            job,
+            newlyStalled: false
+        };
+        const failures = ((_job_failures = job.failures) != null ? _job_failures : 0) + 1;
+        const stalled = failures >= CONSENT_GROUP_CHANGE_STALL_AFTER;
+        const fields = {
+            failures,
+            stalled,
+            lastError,
+            lease: null
+        };
+        transaction.update(jobRef, _extends({}, fields, {
+            updatedAt: FieldValue.serverTimestamp()
+        }));
+        return {
+            job: _extends({}, job, fields),
+            newlyStalled: stalled && !job.stalled
+        };
+    });
+    if (!outcome) return null;
+    if (outcome.newlyStalled) {
+        await ctx.log(outcome.job.orgId, outcome.job.actor, 'A consent group change stopped with an error; it will try again', {
+            type: 'org',
+            id: outcome.job.orgId
+        });
+    }
+    console.error(`[consent-group-change] a unit of ${outcome.job.changeId} failed: ${lastError}`);
+    return outcome.job;
+}
+/**
+ * Advances a change until it finishes, waits for its sweep, or reaches
+ * `deadlineMs`. Answers the job's status either way — including when another
+ * caller holds it, which is not a failure.
+ */ export async function advanceConsentGroupChange(input) {
+    var _input_owner, _ref;
+    const ctx = contextOf(input);
+    const jobRef = jobDoc(ctx, input.orgId, input.changeId);
+    const owner = (_input_owner = input.owner) != null ? _input_owner : `advance:${createResourceUid()}`;
+    const claimed = await claim(ctx, jobRef, owner);
+    if (!claimed) return NOT_FOUND;
+    let job = claimed.job;
+    if (!claimed.mine) return {
+        ok: true,
+        status: consentGroupChangeStatus(job, ctx.now())
+    };
+    try {
+        while(job.status === 'running' && ctx.now() < input.deadlineMs - DEADLINE_SAFETY_MS){
+            const outcome = await advanceOnce(ctx, jobRef, job, owner, input.deadlineMs);
+            job = outcome.job;
+            if (outcome.idle) break;
+        }
+    } catch (error) {
+        var _jobFrom;
+        if (!(error instanceof LeaseLost)) {
+            var _ref1;
+            job = (_ref1 = await recordFailure(ctx, jobRef, owner, error)) != null ? _ref1 : job;
+            return {
+                ok: true,
+                status: consentGroupChangeStatus(job, ctx.now())
+            };
+        }
+        job = (_jobFrom = jobFrom(await jobRef.get())) != null ? _jobFrom : job;
+        return {
+            ok: true,
+            status: consentGroupChangeStatus(job, ctx.now())
+        };
+    }
+    if (job.status === 'running') job = (_ref = await release(ctx, jobRef, owner)) != null ? _ref : job;
+    return {
+        ok: true,
+        status: consentGroupChangeStatus(job, ctx.now())
+    };
+}
+/*==========================================
+ * CANCELING AND READING
+ *=========================================*/ /**
+ * Stops a change before it takes effect: clears the marker and leaves every
+ * refusal already carried, which only ever honors an opt-out on more sites.
+ * Refused once the declaration has flipped — there is nothing left to stop
+ * before, and the only way back is another change.
+ */ export async function cancelConsentGroupChange(input) {
+    var _input_actor_uid, _input_actor_email;
+    const ctx = contextOf(input);
+    const orgRef = orgDoc(ctx, input.orgId);
+    const jobRef = jobDoc(ctx, input.orgId, input.changeId);
+    const outcome = await ctx.firestore.runTransaction(async (transaction)=>{
+        const [orgSnapshot, jobSnapshot] = await Promise.all([
+            transaction.get(orgRef),
+            transaction.get(jobRef)
+        ]);
+        const job = jobFrom(jobSnapshot);
+        if (!job) return NOT_FOUND;
+        if (job.status !== 'running' || job.declaredAtMs) {
+            return {
+                ok: false,
+                status: 409,
+                body: {
+                    error: job.status === 'running' || job.status === 'done' ? 'This change has already taken effect' : 'This change is no longer running',
+                    changeId: job.changeId,
+                    phase: job.phase
+                }
+            };
+        }
+        const marker = readConsentGroupsChange(orgSnapshot.data());
+        if ((marker == null ? void 0 : marker.changeId) === job.changeId) {
+            transaction.update(orgRef, {
+                [CONSENT_GROUPS_CHANGE_FIELD]: FieldValue.delete(),
+                updatedAt: FieldValue.serverTimestamp()
+            });
+        }
+        const fields = {
+            status: 'canceled',
+            phase: 'canceled',
+            canceledAtMs: ctx.now(),
+            lease: null
+        };
+        transaction.update(jobRef, _extends({}, fields, {
+            updatedAt: FieldValue.serverTimestamp()
+        }));
+        return {
+            ok: true,
+            job: _extends({}, job, fields)
+        };
+    });
+    if (isRefusal(outcome)) return outcome;
+    const { job } = outcome;
+    await ctx.log(input.orgId, {
+        uid: (_input_actor_uid = input.actor.uid) != null ? _input_actor_uid : null,
+        email: (_input_actor_email = input.actor.email) != null ? _input_actor_email : null
+    }, 'Canceled a consent group change before it took effect', {
+        type: 'org',
+        id: input.orgId
+    });
+    return {
+        ok: true,
+        status: consentGroupChangeStatus(job, ctx.now())
+    };
+}
+/** A job's status, or `null` for a change the org never had. */ export async function readConsentGroupChangeStatus(input) {
+    const ctx = contextOf(input);
+    const job = jobFrom(await jobDoc(ctx, input.orgId, input.changeId).get());
+    return job ? consentGroupChangeStatus(job, ctx.now()) : null;
+}
+/**
+ * Advances every change in flight, oldest org id first, until `deadlineMs`.
+ *
+ * A change nobody is watching still finishes: the progress panel is a
+ * convenience, and this is the guarantee. A lockdown on the org — or on the
+ * member who started the change — pauses it, like every other write the
+ * workspace makes. A marker whose job document is gone is a change nothing
+ * can finish, and is cleared rather than blocking every change after it.
+ */ export async function advanceDueConsentGroupChanges(input) {
+    var _input_limit;
+    const ctx = contextOf(input);
+    const snapshot = await ctx.firestore.collection('orgs').where(`${CONSENT_GROUPS_CHANGE_FIELD}.phase`, 'in', [
+        ...RUNNING_PHASES
+    ]).limit((_input_limit = input.limit) != null ? _input_limit : 50).get();
+    const reports = [];
+    for (const org of snapshot.docs){
+        const data = org.data();
+        const marker = readConsentGroupsChange(data);
+        if (!marker) continue;
+        const base = {
+            orgId: org.id,
+            changeId: marker.changeId,
+            phase: marker.phase
+        };
+        if (input.dryRun) {
+            reports.push(_extends({}, base, {
+                outcome: 'listed'
+            }));
+            continue;
+        }
+        if (ctx.now() >= input.deadlineMs - DEADLINE_SAFETY_MS) {
+            reports.push(_extends({}, base, {
+                outcome: 'skipped'
+            }));
+            continue;
+        }
+        try {
+            var _ref;
+            var _job_actor;
+            const job = jobFrom(await jobDoc(ctx, org.id, marker.changeId).get());
+            if (!job) {
+                await orgDoc(ctx, org.id).update({
+                    [CONSENT_GROUPS_CHANGE_FIELD]: FieldValue.delete()
+                });
+                console.error(`[consent-group-change] cleared a marker with no job in org ${org.id}`);
+                reports.push(_extends({}, base, {
+                    outcome: 'orphaned'
+                }));
+                continue;
+            }
+            if (await ctx.lockedOut(data, (_ref = (_job_actor = job.actor) == null ? void 0 : _job_actor.uid) != null ? _ref : null)) {
+                reports.push(_extends({}, base, {
+                    outcome: 'locked'
+                }));
+                continue;
+            }
+            const advanced = await advanceConsentGroupChange({
+                orgId: org.id,
+                changeId: marker.changeId,
+                deadlineMs: input.deadlineMs,
+                owner: `cron:${createResourceUid()}`,
+                firestore: ctx.firestore,
+                log: ctx.log,
+                now: ctx.now
+            });
+            reports.push(_extends({}, base, {
+                outcome: 'advanced'
+            }, advanced.ok ? {
+                status: advanced.status
+            } : {}));
+        } catch (error) {
+            reports.push(_extends({}, base, {
+                outcome: 'advanced',
+                error: sanitizeError(error)
+            }));
+        }
+    }
+    return reports;
+}
+
+//# sourceMappingURL=consent-group-change.js.map