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

package/src/lib/server/consent-group-change.d.ts

@@ -0,0 +1,246 @@
+/**
+ * @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 { type ConsentGroupChangeCounts, type ConsentGroupChangePlan, type ConsentGroupChangePreview, type ConsentGroupChangeStatus, type ConsentGroupChangeStep, type ConsentGroupChangeProgress, type ConsentGroupDeclaration, type ConsentGroupsApiInFlight, type ConsentGroupsApiRefusal, type ConsentGroupsApiStale, type ConsentGroupsChangePhase } from '@aglyn/aglyn/app-utils/consent-group-change';
+import { logOrgActivity } from './organizations';
+/** How long a claimed job stays claimed without a renewal. */
+export declare const CONSENT_GROUP_CHANGE_LEASE_MS = 90000;
+/** Consecutive failed units before a job is shown as stalled. */
+export declare const CONSENT_GROUP_CHANGE_STALL_AFTER = 5;
+/** Who asked, as the activity log records it. */
+export interface ConsentGroupChangeActor {
+    uid: string | null;
+    email?: string | null;
+}
+/** Everything the executor reaches outside itself, injectable for the specs. */
+export interface ConsentGroupChangeContext {
+    firestore?: FirebaseFirestore.Firestore;
+    log?: typeof logOrgActivity;
+    now?: () => number;
+    /** Whether a lockdown refuses the cron acting for this org and actor. */
+    lockedOut?: (org: Record<string, unknown>, uid: string | null) => Promise<boolean>;
+}
+/** Where a unit of the current step stands. */
+interface UnitState {
+    cursor: string | null;
+    done: boolean;
+}
+/** The job document, `orgs/{orgId}/consentGroupChanges/{changeId}`. */
+export interface ConsentGroupChangeJob {
+    changeId: string;
+    orgId: string;
+    status: ConsentGroupChangeStatus;
+    step: ConsentGroupChangeStep;
+    /** The marker's phase while running; `done` or `canceled` after. */
+    phase: ConsentGroupsChangePhase | 'done' | 'canceled';
+    /** The steps this change runs, in order. */
+    steps: ConsentGroupChangeStep[];
+    /** The stored declaration it started from: what the flip re-checks. */
+    beforeFingerprint: string;
+    before: ConsentGroupDeclaration;
+    after: ConsentGroupDeclaration;
+    plan: Omit<ConsentGroupChangePlan, 'before' | 'after'>;
+    /** The plan's lines as the activity log writes them. */
+    lines: string[];
+    siteNames: Record<string, string>;
+    /** The participants registered when it started — every one of them runs. */
+    participants: string[];
+    /** The current step's units, by key. */
+    units: Record<string, UnitState>;
+    counts: ConsentGroupChangeCounts;
+    sitesReceiving: string[];
+    plugins: Record<string, Record<string, number>>;
+    lease: {
+        owner: string;
+        untilMs: number;
+    } | null;
+    failures: number;
+    stalled: boolean;
+    lastError: string | null;
+    actor: {
+        uid: string | null;
+        email: string | null;
+    };
+    startedAtMs: number;
+    carryStartedAtMs: number;
+    declaredAtMs: number | null;
+    finishedAtMs: number | null;
+    canceledAtMs: number | null;
+}
+/** What the route answers for a job. */
+export interface ConsentGroupChangeStatusBody {
+    changeId: string;
+    phase: ConsentGroupsChangePhase | 'done' | 'canceled';
+    done: boolean;
+    progress: ConsentGroupChangeProgress;
+}
+/** A refusal the route turns into its status code and body. */
+export type ConsentGroupChangeRefusal = {
+    ok: false;
+    status: 400;
+    body: ConsentGroupsApiRefusal;
+} | {
+    ok: false;
+    status: 404;
+    body: {
+        error: string;
+    };
+} | {
+    ok: false;
+    status: 409;
+    body: ConsentGroupsApiStale | ConsentGroupsApiInFlight;
+};
+export declare function consentGroupChangeStatus(job: ConsentGroupChangeJob, nowMs?: number): ConsentGroupChangeStatusBody;
+/**
+ * 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 declare function previewConsentGroupChange(input: {
+    orgId: string;
+    expected: unknown;
+    groups: unknown;
+    /** The org document, when the caller already read it. */
+    org?: Record<string, unknown> | null;
+} & ConsentGroupChangeContext): Promise<{
+    ok: true;
+    preview: ConsentGroupChangePreview;
+} | ConsentGroupChangeRefusal>;
+/**
+ * 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 declare function startConsentGroupChange(input: {
+    orgId: string;
+    actor: ConsentGroupChangeActor;
+    expected: unknown;
+    groups: unknown;
+} & ConsentGroupChangeContext): Promise<{
+    ok: true;
+    changeId: string;
+    job: ConsentGroupChangeJob;
+} | ConsentGroupChangeRefusal>;
+/**
+ * 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 declare function advanceConsentGroupChange(input: {
+    orgId: string;
+    changeId: string;
+    deadlineMs: number;
+    /** Who holds the lease; one per invocation. */
+    owner?: string;
+} & ConsentGroupChangeContext): Promise<{
+    ok: true;
+    status: ConsentGroupChangeStatusBody;
+} | ConsentGroupChangeRefusal>;
+/**
+ * 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 declare function cancelConsentGroupChange(input: {
+    orgId: string;
+    changeId: string;
+    actor: ConsentGroupChangeActor;
+} & ConsentGroupChangeContext): Promise<{
+    ok: true;
+    status: ConsentGroupChangeStatusBody;
+} | ConsentGroupChangeRefusal>;
+/** A job's status, or `null` for a change the org never had. */
+export declare function readConsentGroupChangeStatus(input: {
+    orgId: string;
+    changeId: string;
+} & ConsentGroupChangeContext): Promise<ConsentGroupChangeStatusBody | null>;
+export interface DueConsentGroupChangeReport {
+    orgId: string;
+    changeId: string;
+    phase: ConsentGroupsChangePhase;
+    /** What happened on this run. */
+    outcome: 'advanced' | 'listed' | 'locked' | 'orphaned' | 'skipped';
+    status?: ConsentGroupChangeStatusBody;
+    error?: string;
+}
+/**
+ * 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 declare function advanceDueConsentGroupChanges(input: {
+    deadlineMs: number;
+    dryRun?: boolean;
+    limit?: number;
+} & ConsentGroupChangeContext): Promise<DueConsentGroupChangeReport[]>;
+export {};