@aglyn/aglyn 1.0.0-beta.196 → 1.0.0-beta.198

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/aglyn",
-  "version": "1.0.0-beta.196",
+  "version": "1.0.0-beta.198",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -33,16 +33,16 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/shared-data-enums": "1.0.0-beta.196",
-    "@aglyn/shared-data-mdi": "1.0.0-beta.196",
-    "@aglyn/shared-data-types": "1.0.0-beta.196",
-    "@aglyn/shared-util-email": "1.0.0-beta.196",
-    "@aglyn/shared-util-first-touch": "1.0.0-beta.196",
-    "@aglyn/shared-util-http": "1.0.0-beta.196",
-    "@aglyn/shared-util-logger": "1.0.0-beta.196",
-    "@aglyn/shared-util-timestamp": "1.0.0-beta.196",
-    "@aglyn/shared-util-tools": "1.0.0-beta.196",
-    "@aglyn/shared-util-vendor": "1.0.0-beta.196",
+    "@aglyn/shared-data-enums": "1.0.0-beta.198",
+    "@aglyn/shared-data-mdi": "1.0.0-beta.198",
+    "@aglyn/shared-data-types": "1.0.0-beta.198",
+    "@aglyn/shared-util-email": "1.0.0-beta.198",
+    "@aglyn/shared-util-first-touch": "1.0.0-beta.198",
+    "@aglyn/shared-util-http": "1.0.0-beta.198",
+    "@aglyn/shared-util-logger": "1.0.0-beta.198",
+    "@aglyn/shared-util-timestamp": "1.0.0-beta.198",
+    "@aglyn/shared-util-tools": "1.0.0-beta.198",
+    "@aglyn/shared-util-vendor": "1.0.0-beta.198",
     "@data-driven-forms/react-form-renderer": "^4.2.0",
     "@msgpack/msgpack": "^3.1.3",
     "@types/unist": "^3.0.3",

package/src/lib/app-utils/consent-group-change.d.ts

@@ -0,0 +1,519 @@
+/**
+ * @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.
+ */
+/**
+ * CHANGING WHICH SITES ARE ONE SENDER (AGL-3320) — the pure half.
+ *
+ * `consent-groups.ts` reads a declaration; this is what a change to one
+ * means. It validates the next declaration an admin submits, decides what has
+ * to move for the sites to stop or start being one sender, and words the
+ * result — and it does all of that without a read, so the console's review
+ * step, the route's refusal and the executor's plan are one computation.
+ *
+ * ## Why a change is a plan and not a write
+ *
+ * A declaration is read at send time, so flipping it is instant — and that is
+ * exactly the problem. Two facts are stored per SITE and read across the
+ * CURRENT group: a refusal (a suppression row, a topic opt-out, a pace, a
+ * declined consent) and a holder's business record (the CRM facet keyed by
+ * the group). When sites stop being one sender, each stops reading the
+ * other's refusals; when they become one, the records they kept apart must
+ * become one. The flip itself moves neither, so every change is:
+ *
+ *  1. CARRY the refusals onto the sites that are about to stop reading them,
+ *     in BOTH directions — the person who left one site of a sender was told
+ *     the opt-out covers all of them, so the site leaving keeps what it
+ *     honored and the sites staying keep what the leaver honored;
+ *  2. FLIP the declaration;
+ *  3. RE-HOME the holder records keyed by the old group ids.
+ *
+ * {@link planConsentGroupChange} says which pairs carry and which holder keys
+ * move or split; the executor in `libs/tenant/data/admin` performs it.
+ *
+ * ## What the planner never touches
+ *
+ * Grants. A grant is written forward, one entry per disclosed site, and is
+ * evidence of what a person was told, so a change never copies, re-keys or
+ * revokes one — see `consent-groups.ts`, "Pooling applies FORWARD only".
+ */
+import { type StoredConsentGroup } from './consent-groups';
+/**
+ * The org field that marks a change in flight:
+ * {@link ConsentGroupsChangeMarker}. Authoritative — the job document holds
+ * the detail, and this says whether there is a job at all.
+ *
+ * On the org document, beside the declaration it guards, so the transaction
+ * that starts a change and the one that flips the declaration read one
+ * document. Server-owned: denied to every client by the rules.
+ */
+export declare const CONSENT_GROUPS_CHANGE_FIELD = "consentGroupsChange";
+/** `orgs/{orgId}/consentGroupChanges/{changeId}` — one job per change. */
+export declare const CONSENT_GROUP_CHANGES_COLLECTION = "consentGroupChanges";
+/**
+ * The longest group name a declaration may carry.
+ *
+ * The name is rendered on every signup form of the group, inside a sentence,
+ * so it is a brand and not a description.
+ */
+export declare const CONSENT_GROUP_NAME_MAX = 80;
+/**
+ * How long after the flip the sweep waits before its final pass.
+ *
+ * A long job — a campaign batch, a dynamic list, an outreach tick — resolves
+ * the group once per batch and runs for at most five minutes, so a write it
+ * made against the OLD declaration can land after the flip. Six minutes is
+ * past the longest of them.
+ */
+export declare const CONSENT_GROUP_SWEEP_DELAY_MS: number;
+/**
+ * What every minted group id starts with.
+ *
+ * A group id is a holder key beside the site ids a solo site is keyed by, so
+ * the two must never meet. Firestore's automatic ids — which every site id is
+ * — are alphanumeric, and an underscore cannot occur in one.
+ */
+export declare const CONSENT_GROUP_ID_PREFIX = "cg_";
+/** Every group of a declaration, by id — what `readConsentGroups` answers. */
+export type ConsentGroupDeclaration = Record<string, StoredConsentGroup>;
+/** One group of the next declaration as the editor submits it. */
+export interface ConsentGroupDraft {
+    /** The id of a group that exists; absent for a new group. */
+    id?: string | null;
+    name: string;
+    hostIds: string[];
+}
+/**
+ * Why a submitted declaration was refused. Every code names something the
+ * admin can fix in the editor; `groupIndex` points at the draft it is about,
+ * and `hostId` at the site.
+ */
+export type ConsentGroupValidationCode = 
+/** Not a list of `{ name, hostIds }` objects. */
+'malformed' | 'name-empty' | 'name-too-long'
+/** Two groups with the same name, ignoring case. */
+ | 'name-duplicate' | 'too-few-sites' | 'too-many-sites'
+/** A site this organization does not own. */
+ | 'unknown-site' | 'site-in-two-groups'
+/** An id no group of the current declaration has. */
+ | 'unknown-group'
+/** One id on two drafts. */
+ | 'duplicate-group'
+/**
+ * A kept id whose sites are ALL new. Keeping the id would carry the old
+ * group's records onto a set of sites none of which kept them; a new group
+ * is what that is.
+ */
+ | 'group-replaced'
+/** The declaration submitted is the one in force. */
+ | 'no-change';
+export interface ConsentGroupValidationError {
+    code: ConsentGroupValidationCode;
+    groupIndex?: number;
+    hostId?: string;
+}
+export type ConsentGroupValidation = {
+    ok: true;
+    after: ConsentGroupDeclaration;
+} | {
+    ok: false;
+    errors: ConsentGroupValidationError[];
+};
+/**
+ * The sites an organization owns, from its `hosts` map, sorted.
+ *
+ * The map is `{ [hostId]: true }`; an array is read too, so a hand-built
+ * fixture and the stored shape agree.
+ */
+export declare function orgSiteIds(org: Record<string, unknown> | null | undefined): string[];
+/** The raw declaration's ids that `readConsentGroups` drops, sorted. */
+export declare function discardedConsentGroupIds(org: Record<string, unknown> | null | undefined): string[];
+/**
+ * A fresh group id: {@link CONSENT_GROUP_ID_PREFIX} and sixteen base-36
+ * characters, never one in `taken`.
+ *
+ * `taken` holds every id the id must not equal — the current groups', the
+ * raw declaration's, every site's and every id already minted for the same
+ * declaration. Eighty bits make a collision a formality, and the loop makes it
+ * impossible.
+ */
+export declare function mintConsentGroupId(taken: ReadonlySet<string>, random?: () => number): string;
+/**
+ * Whether two declarations say the same thing: the same ids, each with the
+ * same trimmed name and the same set of sites. Order never matters.
+ */
+export declare function consentGroupsEqual(a: Record<string, unknown> | null | undefined, b: Record<string, unknown> | null | undefined): boolean;
+/**
+ * A declaration as one canonical string: what "the value the editor
+ * rendered" and "the value stored now" are compared by.
+ *
+ * Every entry is kept, usable or not, because the question is whether the
+ * stored value CHANGED, and an edit to an entry `readConsentGroups` drops is
+ * still somebody else's edit. Absent, `null` and `{}` are one value — an
+ * organization with no groups.
+ */
+export declare function consentGroupsFingerprint(raw: unknown): string;
+/**
+ * The next declaration, checked against the organization's sites and the
+ * declaration in force, with an id minted for every new group.
+ *
+ * Refuses everything in the list on {@link ConsentGroupValidationCode}, and
+ * reports every problem it finds rather than the first, so the editor can
+ * mark each draft at once.
+ */
+export declare function validateConsentGroupDeclaration(input: {
+    groups: unknown;
+    /** The declaration in force: `readConsentGroups(org)`. */
+    before: ConsentGroupDeclaration;
+    /** The organization's sites: {@link orgSiteIds}. */
+    siteIds: readonly string[];
+    /** Ids a minted id must also avoid — the raw declaration's, for one. */
+    reserved?: Iterable<string>;
+    random?: () => number;
+}): ConsentGroupValidation;
+/**
+ * One direction of a carry: `toHostId` is about to stop reading
+ * `fromHostId`'s refusals, so they are copied onto it first.
+ */
+export interface ConsentGroupCarry {
+    toHostId: string;
+    fromHostId: string;
+}
+/**
+ * Every site a holder key covered moves under ONE new key: the key's records
+ * are folded into the new key's, and the old key is deleted in the same
+ * write.
+ */
+export interface ConsentGroupHolderMove {
+    kind: 'move';
+    /** The key the records are under now: a group id, or a solo site's id. */
+    from: string;
+    /** The sites `from` covered. */
+    fromHostIds: string[];
+    /** The key they move under: always a declared group of the next declaration. */
+    to: string;
+    /** The sites of `to` in the next declaration. */
+    toHostIds: string[];
+}
+/**
+ * The sites a holder key covered go separate ways. Each successor may take a
+ * copy of the key's records; the key itself survives when some of its sites
+ * stay under it, and is deleted when none do.
+ */
+export interface ConsentGroupHolderSplit {
+    kind: 'split';
+    from: string;
+    fromHostIds: string[];
+    /** Whether `from` is still a key afterwards. */
+    survives: boolean;
+    /** The sites of `from` that stay under it. Empty when it does not survive. */
+    stayHostIds: string[];
+    /**
+     * Where the other sites go: each successor key with the sites of `from`
+     * that map to it — never the successor's other sites, whose records were
+     * never under `from`.
+     */
+    successors: Array<{
+        key: string;
+        hostIds: string[];
+    }>;
+}
+export type ConsentGroupHolderFlow = ConsentGroupHolderMove | ConsentGroupHolderSplit;
+/** What a change does to the declaration, as the activity log words it. */
+export type ConsentGroupChangeLine = {
+    kind: 'created';
+    groupId: string;
+    name: string;
+    hostIds: string[];
+} | {
+    kind: 'renamed';
+    groupId: string;
+    from: string;
+    to: string;
+} | {
+    kind: 'added';
+    groupId: string;
+    name: string;
+    hostId: string;
+} | {
+    kind: 'removed';
+    groupId: string;
+    name: string;
+    hostId: string;
+} | {
+    kind: 'moved';
+    hostId: string;
+    fromGroupId: string;
+    fromName: string;
+    toGroupId: string;
+    toName: string;
+}
+/** Includes a group absorbed into another: its sites each get a `moved`. */
+ | {
+    kind: 'dissolved';
+    groupId: string;
+    name: string;
+};
+export interface ConsentGroupChangePlan {
+    before: ConsentGroupDeclaration;
+    after: ConsentGroupDeclaration;
+    carries: ConsentGroupCarry[];
+    flows: ConsentGroupHolderFlow[];
+    lines: ConsentGroupChangeLine[];
+    /**
+     * Every site the change touches — whose group, members or group name
+     * changes. What the marker names while the change runs: the sites that
+     * may not be deleted, and whose holder records may be in motion.
+     */
+    hostIds: string[];
+    /** Only names change: nothing to carry and nothing to re-home. */
+    renameOnly: boolean;
+}
+/**
+ * What moving from `before` to `after` requires.
+ *
+ * `key(s)` is the holder key of site `s` — its group's id, or `s` itself when
+ * it is alone — and `members(s)` the sites of that group, or `[s]`.
+ *
+ *  - **Carries.** For every pair a ≠ b that are one sender now and will not
+ *    be, `b`'s refusals are copied onto `a`. Pairs that stay together, and
+ *    pairs that come together, need nothing: a joined site reads its new
+ *    siblings' refusals the moment the declaration names it.
+ *  - **Holder flows.** For each key `k` in force, the sites it covers map to
+ *    a set `T` of keys afterwards. `T = {k}` needs nothing; one other key is
+ *    a MOVE; anything else is a SPLIT, which `k` survives when it is in `T`.
+ *
+ * `siteIds`, when given, are the sites the organization still owns: a site
+ * named by `before` that is gone neither receives a carry nor takes a copy of
+ * a record, because there is nothing left to hold either.
+ */
+export declare function planConsentGroupChange(before: ConsentGroupDeclaration, after: ConsentGroupDeclaration, options?: {
+    siteIds?: readonly string[];
+}): ConsentGroupChangePlan;
+/**
+ * The sites in a sentence: "A", "A and B", "A, B and C".
+ */
+export declare function listSiteNames(names: readonly string[]): string;
+/**
+ * One line of the plan as the organization's activity log says it.
+ *
+ * `siteName` turns a site id into what the console shows for it; the id
+ * itself is the fallback, so a line is never blank.
+ */
+export declare function describeConsentGroupChangeLine(line: ConsentGroupChangeLine, siteName?: (hostId: string) => string): string;
+/**
+ * Where a change stands, on the org marker.
+ *
+ *  - `carry` — copying refusals; the declaration in force is the old one,
+ *    and the change can still be canceled.
+ *  - `rehome` — the new declaration is in force; holder records are moving.
+ *  - `sweep` — waiting out {@link CONSENT_GROUP_SWEEP_DELAY_MS}, then one
+ *    last idempotent pass.
+ */
+export type ConsentGroupsChangePhase = 'carry' | 'rehome' | 'sweep';
+/** `org.consentGroupsChange` — present exactly while a change runs. */
+export interface ConsentGroupsChangeMarker {
+    changeId: string;
+    phase: ConsentGroupsChangePhase;
+    /** {@link ConsentGroupChangePlan.hostIds}. */
+    hostIds: string[];
+    startedAtMs: number;
+    /** When the new declaration took effect; absent before the flip. */
+    declaredAtMs?: number;
+}
+/** The marker off an org document, or `null` when no change is in flight. */
+export declare function readConsentGroupsChange(org: Record<string, unknown> | null | undefined): ConsentGroupsChangeMarker | null;
+/**
+ * Whether the holder records `hostId` reads may be mid-move: a change in
+ * flight has flipped the declaration and names this site.
+ *
+ * A reader that decides something by a record's ABSENCE — a dynamic list
+ * that removes whoever no longer matches — must not decide it while this
+ * holds, because a record that has not moved yet reads as missing.
+ */
+export declare function consentGroupHoldersInMotion(org: Record<string, unknown> | null | undefined, hostId: string): boolean;
+/**
+ * The executor's steps, in order.
+ *
+ *  - `carry` — every carry, then every participant's carry phase.
+ *  - `catch-up-pre` — the refusals filed since the carry began.
+ *  - `declare` — the flip, in one transaction.
+ *  - `catch-up-post` — the same catch-up, for what raced the flip.
+ *  - `rehome` — every participant's holder records.
+ *  - `sweep-wait` — until {@link CONSENT_GROUP_SWEEP_DELAY_MS} has passed.
+ *  - `sweep` — every carry again in full, and every participant's sweep.
+ *  - `finish` — the marker cleared.
+ *
+ * A rename-only change runs `declare` and `finish` alone.
+ */
+export declare const CONSENT_GROUP_CHANGE_STEPS: readonly ["carry", "catch-up-pre", "declare", "catch-up-post", "rehome", "sweep-wait", "sweep", "finish"];
+export type ConsentGroupChangeStep = (typeof CONSENT_GROUP_CHANGE_STEPS)[number];
+/** The steps a rename-only change runs. */
+export declare const CONSENT_GROUP_RENAME_STEPS: readonly ConsentGroupChangeStep[];
+/** The marker phase a step runs under. */
+export declare function consentGroupChangePhaseOf(step: ConsentGroupChangeStep): ConsentGroupsChangePhase;
+export type ConsentGroupChangeStatus = 'running' | 'done' | 'canceled';
+/** What the refusal carries copied so far, across every step. */
+export interface ConsentGroupChangeCounts {
+    siteSuppressions: number;
+    topicOptOuts: number;
+    paces: number;
+}
+/** A job's state, as the route answers it and the progress panel renders it. */
+export interface ConsentGroupChangeProgress {
+    status: ConsentGroupChangeStatus;
+    step: ConsentGroupChangeStep;
+    /** 1-based position of `step` among the steps this change runs. */
+    stepIndex: number;
+    stepCount: number;
+    /** When the new declaration took effect, or `null` before the flip. */
+    declaredAtMs: number | null;
+    /** When the sweep may start, or `null` before the flip. */
+    sweepAtMs: number | null;
+    /** Five units in a row failed. The change keeps retrying. */
+    stalled: boolean;
+    /** Consecutive failed units. */
+    failures: number;
+    lastError: string | null;
+    /** Until when another caller holds the job; `null` when it is free. */
+    leaseUntilMs: number | null;
+    counts: ConsentGroupChangeCounts;
+    /** The sites that received at least one carried refusal. */
+    sitesReceiving: number;
+    /** Each participant's counts, by plugin id. */
+    plugins: Record<string, Record<string, number>>;
+}
+export type ConsentGroupsApiAction = 'preview' | 'apply' | 'continue' | 'cancel' | 'status';
+export interface ConsentGroupsApiDeclarationRequest {
+    orgId: string;
+    action: 'preview' | 'apply';
+    /**
+     * `org.consentGroups` exactly as the editor rendered it, or `null` for an
+     * organization with none. Compared by {@link consentGroupsFingerprint}.
+     */
+    expected: Record<string, unknown> | null;
+    /** The COMPLETE next declaration. A new group has no id. */
+    groups: ConsentGroupDraft[];
+}
+export interface ConsentGroupsApiChangeRequest {
+    orgId: string;
+    action: 'continue' | 'cancel' | 'status';
+    changeId: string;
+}
+export type ConsentGroupsApiRequest = ConsentGroupsApiDeclarationRequest | ConsentGroupsApiChangeRequest;
+/** 200 for `preview`. */
+export interface ConsentGroupsApiPreviewResponse {
+    ok: true;
+    preview: ConsentGroupChangePreview;
+}
+/** 200 for `apply`, `continue`, `cancel` and `status`. */
+export interface ConsentGroupsApiChangeResponse {
+    ok: true;
+    changeId: string;
+    phase: ConsentGroupsChangePhase | 'done' | 'canceled';
+    done: boolean;
+    progress: ConsentGroupChangeProgress;
+}
+/** 400: the declaration was refused. */
+export interface ConsentGroupsApiRefusal {
+    error: string;
+    errors: ConsentGroupValidationError[];
+}
+/** 409: the declaration changed since the editor rendered it. */
+export interface ConsentGroupsApiStale {
+    error: string;
+    current: Record<string, unknown> | null;
+}
+/** 409: another change is running, or a cancel came after the flip. */
+export interface ConsentGroupsApiInFlight {
+    error: string;
+    changeId: string;
+    phase: ConsentGroupsChangePhase | 'done' | 'canceled';
+}
+/**
+ * One sentence a participant adds to the review step, with the figure it is
+ * about. `id` is namespaced by the participant (`crm.combine`).
+ */
+export interface ConsentGroupChangePreviewLine {
+    id: string;
+    text: string;
+    count: number | null;
+    severity: 'info' | 'warning';
+}
+/** How long a change should take, from the work the preview counted. */
+export type ConsentGroupChangeEstimate = 'instant' | 'under-a-minute' | 'minutes' | 'long';
+/** The work bands behind {@link ConsentGroupChangeEstimate}. */
+export declare function estimateConsentGroupChange(plan: Pick<ConsentGroupChangePlan, 'renameOnly'>, documents: number): ConsentGroupChangeEstimate;
+export interface ConsentGroupChangePreview {
+    before: ConsentGroupDeclaration;
+    after: ConsentGroupDeclaration;
+    /** Stored ids `readConsentGroups` drops; the write removes them. */
+    discarded: string[];
+    /** The plan's lines, each with the sentence the activity log will write. */
+    lines: Array<ConsentGroupChangeLine & {
+        text: string;
+    }>;
+    /** Every group whose signup-form sentence changes. */
+    disclosures: Array<{
+        groupId: string;
+        hostIds: string[];
+        before: string | null;
+        after: string | null;
+    }>;
+    /** Per carry, what the source site holds now (count aggregations). */
+    carries: Array<{
+        toHostId: string;
+        fromHostId: string;
+        siteSuppressions: number;
+        topicOptOuts: number;
+        paces: number;
+    }>;
+    /** Per joining site, the refusals on its new siblings it starts honoring. */
+    inherited: Array<{
+        hostId: string;
+        refusals: number;
+    }>;
+    /**
+     * Pending confirmations that stop holding a separated site's mail. Only
+     * when the organization's confirmation switch is on.
+     */
+    pendingHolds: Array<{
+        hostId: string;
+        topicId: string;
+        count: number;
+        releasedHostIds: string[];
+    }>;
+    /** Team members who can open only some of a changed group's sites. */
+    partialAccessMembers: number;
+    /**
+     * Set when the organization's consent policy is `forward` and a site joins:
+     * the joining sites may email people their new siblings captured before
+     * `enforceFromMs` without a recorded opt-in.
+     */
+    forwardPolicyWarning: {
+        hostIds: string[];
+        enforceFromMs: number;
+    } | null;
+    /** Each participant's lines; `null` for one whose preview failed. */
+    participants: Array<{
+        pluginId: string;
+        lines: ConsentGroupChangePreviewLine[] | null;
+    }>;
+    /** The capture surfaces that show a group's disclosure. */
+    capturesDisclosing: string[];
+    estimate: ConsentGroupChangeEstimate;
+}
+/** The groups whose disclosure sentence differs between the declarations. */
+export declare function consentGroupDisclosureChanges(before: ConsentGroupDeclaration, after: ConsentGroupDeclaration): ConsentGroupChangePreview['disclosures'];