@oxygen-agent/cli 1.1014.1136 → 1.1014.1219

package/node_modules/@oxygen/shared/dist/deliverability-evidence.d.ts

@@ -0,0 +1,366 @@
+import type { DeliverabilityCheckKind, DeliverabilityFindingStatus, DeliverabilityRunStatus, PlacementFolder, PlacementObservation, PlacementObservationSource, PlacementReceiverProvider, PlacementTab } from "./deliverability-checks.js";
+/**
+ * The deliverability learning loop's read contract: evidence over stored check runs, placement
+ * observations and real campaign outcomes. Every rate carries its numerator, denominator and what
+ * the denominator counts; an empty bucket is reported as zeros, never interpolated.
+ */
+export declare const DELIVERABILITY_EVIDENCE_BUCKETS: readonly ["day", "week"];
+export type DeliverabilityEvidenceBucketSize = (typeof DELIVERABILITY_EVIDENCE_BUCKETS)[number];
+/** Window bound per bucket size; a week window covers the whole 400-day retention. */
+export declare const DELIVERABILITY_EVIDENCE_MAX_BUCKETS: Record<DeliverabilityEvidenceBucketSize, number>;
+/** Below this denominator a rate is still reported, but flagged as a low sample. */
+export declare const DELIVERABILITY_EVIDENCE_MIN_SAMPLE = 8;
+export declare const DELIVERABILITY_EVIDENCE_MAX_CONTENT_HASHES = 10;
+export declare const DELIVERABILITY_EVIDENCE_MAX_CHANGES = 100;
+export declare const DELIVERABILITY_EVIDENCE_MAX_SIGNALS = 50;
+/** Domain-subject checks whose latest state and status changes the evidence reports. */
+export declare const DELIVERABILITY_EVIDENCE_DOMAIN_CHECKS: readonly ["dns_auth", "bimi", "blacklist"];
+/** Content-score findings name each triggered rule as `content.rule.<symbol>`. */
+export declare const DELIVERABILITY_CONTENT_RULE_PREFIX = "content.rule.";
+/** Placement time: when the probe was sent, else when it was read, else when it was stored. */
+export declare const PLACEMENT_EVIDENCE_TIME = "sent_at, else observed_at, else recorded_at";
+/**
+ * Placement-change Signals: a sender domain × receiver provider pair is compared over a rolling
+ * current window against the window before it. Placement is directional evidence only, so a
+ * transition emits a Signal and never pauses a sender.
+ */
+export declare const PLACEMENT_SIGNAL_CURRENT_WINDOW_DAYS = 7;
+export declare const PLACEMENT_SIGNAL_BASELINE_WINDOW_DAYS = 28;
+/** Settled probes (inbox, spam, other or not observed) each window needs before a rate is trusted. */
+export declare const PLACEMENT_SIGNAL_MIN_SAMPLE = 8;
+/** Absolute inbox-rate drop (0.25 = 25 percentage points) that counts as a transition. */
+export declare const PLACEMENT_SIGNAL_INBOX_DROP = 0.25;
+/** Gmail-tab-classified inbox probes each window needs before a tab shift is trusted. */
+export declare const PLACEMENT_SIGNAL_MIN_TAB_SAMPLE = 6;
+/** Primary share must fall, and Promotions share rise, by at least this much. */
+export declare const PLACEMENT_SIGNAL_TAB_SHIFT = 0.25;
+/** One Signal per domain × provider × transition within this many days. */
+export declare const PLACEMENT_SIGNAL_COOLDOWN_DAYS = 7;
+export declare const PLACEMENT_SIGNAL_MAX_PAIRS = 500;
+export declare const PLACEMENT_SIGNAL_MAX_EMITS = 50;
+export declare const PLACEMENT_SIGNAL_TYPE = "placement_changed";
+export declare const PLACEMENT_SIGNAL_SOURCE_PROVIDER = "oxygen_deliverability";
+export declare const PLACEMENT_SIGNAL_SCHEMA = "placement_changed.v1";
+export declare const PLACEMENT_TRANSITIONS: readonly ["inbox_rate_drop", "primary_to_promotions"];
+export type PlacementTransitionKind = (typeof PLACEMENT_TRANSITIONS)[number];
+export declare const PLACEMENT_COUNT_OUTCOMES: readonly ["observed", "not_observed", "send_failed", "send_unknown", "read_blocked"];
+export declare const PLACEMENT_COUNT_FOLDERS: readonly ["inbox", "spam", "other", "not_observed", "unknown"];
+export declare const PLACEMENT_COUNT_TABS: readonly ["primary", "promotions", "social", "updates", "forums", "focused", "other", "unknown"];
+/** Raw placement counts for one scope; `tabs` counts inbox observations only. */
+export type PlacementCounts = {
+    probes: number;
+    outcomes: Record<PlacementObservation["outcome"], number>;
+    folders: Record<PlacementFolder, number>;
+    tabs: Record<PlacementTab, number>;
+    spf: {
+        known: number;
+        pass: number;
+    };
+    dkim: {
+        known: number;
+        pass: number;
+    };
+    dmarc: {
+        known: number;
+        pass: number;
+    };
+    aligned: {
+        known: number;
+        pass: number;
+    };
+    contentScore: {
+        sampleSize: number;
+        sum: number;
+    };
+};
+export type DeliverabilityRate = {
+    /** numerator / denominator rounded to 4 places; null when the denominator is 0. */
+    value: number | null;
+    numerator: number;
+    denominator: number;
+    /** What the denominator counts, e.g. `settled_probes`. */
+    denominatorOf: string;
+    lowSample: boolean;
+};
+export declare function deliverabilityRate(numerator: number, denominator: number, denominatorOf: string, minSample?: number): DeliverabilityRate;
+export type PlacementEvidence = {
+    probes: number;
+    outcomes: Record<PlacementObservation["outcome"], number>;
+    folders: Record<PlacementFolder, number>;
+    /** Inbox observations by tab; `unknown` when the receiver did not classify the message. */
+    tabs: Record<PlacementTab, number>;
+    /** Settled probes: inbox, spam, other or not observed. Failed sends and blocked reads are excluded. */
+    settled: number;
+    inboxRate: DeliverabilityRate;
+    spamRate: DeliverabilityRate;
+    notObservedRate: DeliverabilityRate;
+    /** Gmail tabs: share of inbox probes Gmail classified into a tab. */
+    primaryRate: DeliverabilityRate;
+    promotionsRate: DeliverabilityRate;
+    /** Outlook: Focused share of inbox probes classified Focused or Other. */
+    focusedRate: DeliverabilityRate;
+    spfPassRate: DeliverabilityRate;
+    dkimPassRate: DeliverabilityRate;
+    dmarcPassRate: DeliverabilityRate;
+    alignedRate: DeliverabilityRate;
+    contentScore: {
+        average: number | null;
+        sampleSize: number;
+    };
+};
+export declare function emptyPlacementCounts(): PlacementCounts;
+export declare function settledPlacementProbes(counts: PlacementCounts): number;
+export declare function summarizePlacementCounts(counts: PlacementCounts): PlacementEvidence;
+/** Real campaign outcomes in the same period; bounces and replies are period co-occurrence, not a send cohort. */
+export type CampaignOutcomes = {
+    sends: number;
+    bounces: number;
+    replies: number;
+    bounceRate: DeliverabilityRate;
+    replyRate: DeliverabilityRate;
+};
+export declare function campaignOutcomes(sends: number, bounces: number, replies: number): CampaignOutcomes;
+export type DeliverabilityEvidenceQuery = {
+    senderDomain?: string;
+    senderMailboxId?: string;
+    contentHash?: string;
+    receiverProvider?: PlacementReceiverProvider;
+    since: string;
+    until: string;
+    bucket: DeliverabilityEvidenceBucketSize;
+};
+export type DeliverabilityCheckState = {
+    kind: DeliverabilityCheckKind;
+    subject: string;
+    /** `never_run` when no run of this kind exists for the subject before the window end. */
+    state: DeliverabilityRunStatus | "never_run";
+    runId: string | null;
+    startedAt: string | null;
+    findingCounts: Record<DeliverabilityFindingStatus, number>;
+    failing: string[];
+    warning: string[];
+};
+export type DeliverabilityFindingChange = {
+    kind: DeliverabilityCheckKind;
+    subject: string;
+    check: string;
+    from: DeliverabilityFindingStatus;
+    to: DeliverabilityFindingStatus;
+    at: string;
+    runId: string;
+};
+export type PlacementChangeSignalRef = {
+    id: string;
+    occurredAt: string;
+    transition: PlacementTransitionKind;
+    senderDomain: string;
+    receiverProvider: PlacementReceiverProvider;
+    summary: string | null;
+};
+/**
+ * A capped list that says it is capped: `total` counts every match in the window, `items` holds
+ * at most the cap in `order`, and `truncated` is true when `total` exceeds `items.length`.
+ */
+export type DeliverabilityEvidenceList<T> = {
+    items: T[];
+    total: number;
+    truncated: boolean;
+    order: string;
+};
+export declare function deliverabilityEvidenceList<T>(items: T[], total: number, order: string): DeliverabilityEvidenceList<T>;
+export type DeliverabilityEvidenceBucket = {
+    start: string;
+    end: string;
+    placement: PlacementEvidence;
+    /** Null when campaign outcomes cannot be narrowed to this subject (see `campaignAvailability`). */
+    campaign: CampaignOutcomes | null;
+};
+export type DeliverabilityEvidence = {
+    subject: {
+        senderDomain: string | null;
+        senderMailboxId: string | null;
+        contentHash: string | null;
+        receiverProvider: PlacementReceiverProvider | null;
+        /** The domain whose checks are reported: the filter, or the sender mailbox's domain. */
+        checkedDomain: string | null;
+    };
+    window: {
+        since: string;
+        until: string;
+        bucket: DeliverabilityEvidenceBucketSize;
+        timezone: "UTC";
+        bucketCount: number;
+    };
+    basis: {
+        placementTime: string;
+        campaign: string;
+    };
+    totals: {
+        placement: PlacementEvidence;
+        campaign: CampaignOutcomes | null;
+    };
+    buckets: DeliverabilityEvidenceBucket[];
+    byReceiverProvider: Array<{
+        receiverProvider: PlacementReceiverProvider;
+        placement: PlacementEvidence;
+    }>;
+    bySource: Array<{
+        source: PlacementObservationSource;
+        probes: number;
+    }>;
+    campaignAvailability: {
+        available: boolean;
+        reason: string | null;
+    };
+    checks: DeliverabilityCheckState[];
+    /** Copy hashes seen in the window, most probes first. */
+    contentScores: DeliverabilityEvidenceList<{
+        contentHash: string;
+        probes: number;
+        latest: DeliverabilityCheckState;
+    }>;
+    /** Finding status changes of the checked domain, newest first. */
+    changes: DeliverabilityEvidenceList<DeliverabilityFindingChange>;
+    /** Placement Signals emitted in the window, newest first. */
+    signals: DeliverabilityEvidenceList<PlacementChangeSignalRef>;
+};
+/** How many UTC-aligned buckets a window spans, computed without building them, so a bound can be checked first. */
+export declare function deliverabilityEvidenceBucketCount(since: Date, until: Date, bucket: DeliverabilityEvidenceBucketSize): number;
+export declare function deliverabilityEvidenceBuckets(since: Date, until: Date, bucket: DeliverabilityEvidenceBucketSize): {
+    origin: Date;
+    stepMs: number;
+    buckets: Array<{
+        start: Date;
+        end: Date;
+    }>;
+};
+export type PlacementRunSide = {
+    ref: string;
+    sources: PlacementObservationSource[];
+    at: string;
+    senderDomains: string[];
+    contentHashes: string[];
+    variantKeys: string[];
+    placement: PlacementEvidence;
+};
+export type DeliverabilityCheckSide = {
+    runId: string;
+    kind: DeliverabilityCheckKind;
+    subject: string;
+    status: DeliverabilityRunStatus;
+    startedAt: string;
+    engineVersion: string | null;
+    findingCounts: Record<DeliverabilityFindingStatus, number>;
+};
+export type DeliverabilityFindingDiff = {
+    check: string;
+    a: DeliverabilityFindingStatus | null;
+    b: DeliverabilityFindingStatus | null;
+};
+export type DeliverabilityRuleSymbolDiff = {
+    added: string[];
+    removed: string[];
+};
+export type DeliverabilityComparison = {
+    kind: "placement";
+    a: PlacementRunSide;
+    b: PlacementRunSide;
+    byReceiverProvider: Array<{
+        receiverProvider: PlacementReceiverProvider;
+        a: PlacementEvidence;
+        b: PlacementEvidence;
+        inboxRateDelta: number | null;
+    }>;
+    inboxRateDelta: number | null;
+    content: {
+        changed: boolean;
+        /** Copy hashes of either run, sorted; rule symbols are diffed over the listed hashes only. */
+        scores: DeliverabilityEvidenceList<{
+            contentHash: string;
+            side: "a" | "b" | "both";
+            latest: DeliverabilityCheckState;
+        }>;
+        ruleSymbols: DeliverabilityRuleSymbolDiff;
+    };
+    /** Sender domains of either run, sorted; domain checks are compared for the listed domains only. */
+    domains: DeliverabilityEvidenceList<string>;
+    /** Domain check states as of each run's time; only checks whose status differs are listed. */
+    findingChanges: Array<{
+        kind: DeliverabilityCheckKind;
+        subject: string;
+        aRunId: string | null;
+        bRunId: string | null;
+        changes: DeliverabilityFindingDiff[];
+    }>;
+} | {
+    kind: "check";
+    checkKind: DeliverabilityCheckKind;
+    a: DeliverabilityCheckSide;
+    b: DeliverabilityCheckSide;
+    sameSubject: boolean;
+    changes: DeliverabilityFindingDiff[];
+    unchanged: number;
+    ruleSymbols: DeliverabilityRuleSymbolDiff | null;
+};
+/** Status by check code on each side → only the codes whose status differs. */
+export declare function diffFindingStatuses(a: ReadonlyMap<string, DeliverabilityFindingStatus>, b: ReadonlyMap<string, DeliverabilityFindingStatus>): {
+    changes: DeliverabilityFindingDiff[];
+    unchanged: number;
+};
+export declare function diffRuleSymbols(a: Iterable<string>, b: Iterable<string>): DeliverabilityRuleSymbolDiff;
+export type PlacementTransition = {
+    transition: PlacementTransitionKind;
+    senderDomain: string;
+    receiverProvider: PlacementReceiverProvider;
+    baseline: DeliverabilityRate;
+    current: DeliverabilityRate;
+    /** current − baseline of the measured rate (negative for a drop). */
+    delta: number;
+    threshold: number;
+    /** The minimum denominator each window needed; it counts what `baseline.denominatorOf` names. */
+    minSample: number;
+    /** The second rate a tab shift also requires (Promotions share). */
+    secondary?: {
+        baseline: DeliverabilityRate;
+        current: DeliverabilityRate;
+        delta: number;
+    };
+};
+/** Pure transition rules; the thresholds above are the whole policy. */
+export declare function detectPlacementTransitions(input: {
+    senderDomain: string;
+    receiverProvider: PlacementReceiverProvider;
+    baseline: PlacementCounts;
+    current: PlacementCounts;
+}): PlacementTransition[];
+export declare function placementTransitionSummary(t: PlacementTransition): string;
+/** The Signal's typed payload (`ox_model.activities.metadata`), versioned by `schema`. */
+export type PlacementChangeSignalMetadata = {
+    schema: typeof PLACEMENT_SIGNAL_SCHEMA;
+    transition: PlacementTransitionKind;
+    sender_domain: string;
+    receiver_provider: PlacementReceiverProvider;
+    window: {
+        baseline_since: string;
+        current_since: string;
+        until: string;
+    };
+    baseline: DeliverabilityRate;
+    current: DeliverabilityRate;
+    delta: number;
+    threshold: number;
+    /** Minimum denominator per window for this transition; it counts `baseline.denominatorOf`. */
+    min_sample: number;
+    secondary: PlacementTransition["secondary"] | null;
+    /**
+     * Sample sizes behind the transition. `*_settled` always counts settled probes; the Gmail-tab
+     * counts are the Primary/Promotions denominators, set only for `primary_to_promotions`.
+     */
+    evidence: {
+        baseline_settled: number;
+        current_settled: number;
+        baseline_gmail_tabbed: number | null;
+        current_gmail_tabbed: number | null;
+        latest_observation_at: string | null;
+    };
+};

package/node_modules/@oxygen/shared/dist/deliverability-evidence.js

@@ -0,0 +1,169 @@
+/**
+ * The deliverability learning loop's read contract: evidence over stored check runs, placement
+ * observations and real campaign outcomes. Every rate carries its numerator, denominator and what
+ * the denominator counts; an empty bucket is reported as zeros, never interpolated.
+ */
+export const DELIVERABILITY_EVIDENCE_BUCKETS = ["day", "week"];
+/** Window bound per bucket size; a week window covers the whole 400-day retention. */
+export const DELIVERABILITY_EVIDENCE_MAX_BUCKETS = { day: 120, week: 60 };
+/** Below this denominator a rate is still reported, but flagged as a low sample. */
+export const DELIVERABILITY_EVIDENCE_MIN_SAMPLE = 8;
+export const DELIVERABILITY_EVIDENCE_MAX_CONTENT_HASHES = 10;
+export const DELIVERABILITY_EVIDENCE_MAX_CHANGES = 100;
+export const DELIVERABILITY_EVIDENCE_MAX_SIGNALS = 50;
+/** Domain-subject checks whose latest state and status changes the evidence reports. */
+export const DELIVERABILITY_EVIDENCE_DOMAIN_CHECKS = ["dns_auth", "bimi", "blacklist"];
+/** Content-score findings name each triggered rule as `content.rule.<symbol>`. */
+export const DELIVERABILITY_CONTENT_RULE_PREFIX = "content.rule.";
+/** Placement time: when the probe was sent, else when it was read, else when it was stored. */
+export const PLACEMENT_EVIDENCE_TIME = "sent_at, else observed_at, else recorded_at";
+/**
+ * Placement-change Signals: a sender domain × receiver provider pair is compared over a rolling
+ * current window against the window before it. Placement is directional evidence only, so a
+ * transition emits a Signal and never pauses a sender.
+ */
+export const PLACEMENT_SIGNAL_CURRENT_WINDOW_DAYS = 7;
+export const PLACEMENT_SIGNAL_BASELINE_WINDOW_DAYS = 28;
+/** Settled probes (inbox, spam, other or not observed) each window needs before a rate is trusted. */
+export const PLACEMENT_SIGNAL_MIN_SAMPLE = 8;
+/** Absolute inbox-rate drop (0.25 = 25 percentage points) that counts as a transition. */
+export const PLACEMENT_SIGNAL_INBOX_DROP = 0.25;
+/** Gmail-tab-classified inbox probes each window needs before a tab shift is trusted. */
+export const PLACEMENT_SIGNAL_MIN_TAB_SAMPLE = 6;
+/** Primary share must fall, and Promotions share rise, by at least this much. */
+export const PLACEMENT_SIGNAL_TAB_SHIFT = 0.25;
+/** One Signal per domain × provider × transition within this many days. */
+export const PLACEMENT_SIGNAL_COOLDOWN_DAYS = 7;
+export const PLACEMENT_SIGNAL_MAX_PAIRS = 500;
+export const PLACEMENT_SIGNAL_MAX_EMITS = 50;
+export const PLACEMENT_SIGNAL_TYPE = "placement_changed";
+export const PLACEMENT_SIGNAL_SOURCE_PROVIDER = "oxygen_deliverability";
+export const PLACEMENT_SIGNAL_SCHEMA = "placement_changed.v1";
+export const PLACEMENT_TRANSITIONS = ["inbox_rate_drop", "primary_to_promotions"];
+const OUTCOMES = ["observed", "not_observed", "send_failed", "send_unknown", "read_blocked"];
+const FOLDERS = ["inbox", "spam", "other", "not_observed", "unknown"];
+const TABS = ["primary", "promotions", "social", "updates", "forums", "focused", "other", "unknown"];
+const GMAIL_TABS = ["primary", "promotions", "social", "updates", "forums"];
+export const PLACEMENT_COUNT_OUTCOMES = OUTCOMES;
+export const PLACEMENT_COUNT_FOLDERS = FOLDERS;
+export const PLACEMENT_COUNT_TABS = TABS;
+export function deliverabilityRate(numerator, denominator, denominatorOf, minSample = DELIVERABILITY_EVIDENCE_MIN_SAMPLE) {
+    return {
+        value: denominator > 0 ? Math.round((numerator / denominator) * 10_000) / 10_000 : null,
+        numerator, denominator, denominatorOf, lowSample: denominator < minSample,
+    };
+}
+const zeros = (keys) => Object.fromEntries(keys.map((key) => [key, 0]));
+export function emptyPlacementCounts() {
+    return {
+        probes: 0, outcomes: zeros(OUTCOMES), folders: zeros(FOLDERS), tabs: zeros(TABS),
+        spf: { known: 0, pass: 0 }, dkim: { known: 0, pass: 0 }, dmarc: { known: 0, pass: 0 }, aligned: { known: 0, pass: 0 },
+        contentScore: { sampleSize: 0, sum: 0 },
+    };
+}
+export function settledPlacementProbes(counts) {
+    return counts.folders.inbox + counts.folders.spam + counts.folders.other + counts.folders.not_observed;
+}
+const gmailTabbed = (counts) => GMAIL_TABS.reduce((sum, tab) => sum + counts.tabs[tab], 0);
+export function summarizePlacementCounts(counts) {
+    const settled = settledPlacementProbes(counts);
+    const gmail = gmailTabbed(counts);
+    const outlook = counts.tabs.focused + counts.tabs.other;
+    return {
+        probes: counts.probes, outcomes: { ...counts.outcomes }, folders: { ...counts.folders }, tabs: { ...counts.tabs }, settled,
+        inboxRate: deliverabilityRate(counts.folders.inbox, settled, "settled_probes"),
+        spamRate: deliverabilityRate(counts.folders.spam, settled, "settled_probes"),
+        notObservedRate: deliverabilityRate(counts.folders.not_observed, settled, "settled_probes"),
+        primaryRate: deliverabilityRate(counts.tabs.primary, gmail, "inbox_probes_with_gmail_tab", PLACEMENT_SIGNAL_MIN_TAB_SAMPLE),
+        promotionsRate: deliverabilityRate(counts.tabs.promotions, gmail, "inbox_probes_with_gmail_tab", PLACEMENT_SIGNAL_MIN_TAB_SAMPLE),
+        focusedRate: deliverabilityRate(counts.tabs.focused, outlook, "inbox_probes_with_outlook_focus", PLACEMENT_SIGNAL_MIN_TAB_SAMPLE),
+        spfPassRate: deliverabilityRate(counts.spf.pass, counts.spf.known, "probes_with_spf_result"),
+        dkimPassRate: deliverabilityRate(counts.dkim.pass, counts.dkim.known, "probes_with_dkim_result"),
+        dmarcPassRate: deliverabilityRate(counts.dmarc.pass, counts.dmarc.known, "probes_with_dmarc_result"),
+        alignedRate: deliverabilityRate(counts.aligned.pass, counts.aligned.known, "probes_with_alignment_result"),
+        contentScore: {
+            average: counts.contentScore.sampleSize > 0 ? Math.round((counts.contentScore.sum / counts.contentScore.sampleSize) * 100) / 100 : null,
+            sampleSize: counts.contentScore.sampleSize,
+        },
+    };
+}
+export function campaignOutcomes(sends, bounces, replies) {
+    return { sends, bounces, replies, bounceRate: deliverabilityRate(bounces, sends, "campaign_sends"), replyRate: deliverabilityRate(replies, sends, "campaign_sends") };
+}
+export function deliverabilityEvidenceList(items, total, order) {
+    const count = Math.max(total, items.length);
+    return { items, total: count, truncated: count > items.length, order };
+}
+/** UTC calendar buckets covering [since, until); the outer buckets are clipped to the window. */
+function evidenceBucketGrid(since, bucket) {
+    const day = 86_400_000;
+    const stepMs = bucket === "day" ? day : 7 * day;
+    const floorDay = Math.floor(since.getTime() / day) * day;
+    // 1970-01-01 was a Thursday; ISO weeks start on Monday.
+    return { origin: bucket === "day" ? floorDay : floorDay - (((new Date(floorDay).getUTCDay() + 6) % 7) * day), stepMs };
+}
+/** How many UTC-aligned buckets a window spans, computed without building them, so a bound can be checked first. */
+export function deliverabilityEvidenceBucketCount(since, until, bucket) {
+    const { origin, stepMs } = evidenceBucketGrid(since, bucket);
+    return Math.max(0, Math.ceil((until.getTime() - origin) / stepMs));
+}
+export function deliverabilityEvidenceBuckets(since, until, bucket) {
+    const { origin, stepMs } = evidenceBucketGrid(since, bucket);
+    const buckets = [];
+    for (let start = origin; start < until.getTime(); start += stepMs) {
+        buckets.push({ start: new Date(Math.max(start, since.getTime())), end: new Date(Math.min(start + stepMs, until.getTime())) });
+    }
+    return { origin: new Date(origin), stepMs, buckets };
+}
+/** Status by check code on each side → only the codes whose status differs. */
+export function diffFindingStatuses(a, b) {
+    const codes = [...new Set([...a.keys(), ...b.keys()])].sort();
+    const changes = [];
+    let unchanged = 0;
+    for (const check of codes) {
+        const left = a.get(check) ?? null;
+        const right = b.get(check) ?? null;
+        if (left === right)
+            unchanged += 1;
+        else
+            changes.push({ check, a: left, b: right });
+    }
+    return { changes, unchanged };
+}
+export function diffRuleSymbols(a, b) {
+    const symbols = (codes) => new Set([...codes].filter((code) => code.startsWith(DELIVERABILITY_CONTENT_RULE_PREFIX)).map((code) => code.slice(DELIVERABILITY_CONTENT_RULE_PREFIX.length)));
+    const left = symbols(a);
+    const right = symbols(b);
+    return { added: [...right].filter((s) => !left.has(s)).sort(), removed: [...left].filter((s) => !right.has(s)).sort() };
+}
+const round4 = (value) => Math.round(value * 10_000) / 10_000;
+// Rates are rounded to 4 places, so a threshold met exactly must not miss on float noise.
+const meets = (delta, threshold) => delta >= threshold - 1e-9;
+/** Pure transition rules; the thresholds above are the whole policy. */
+export function detectPlacementTransitions(input) {
+    const base = summarizePlacementCounts(input.baseline);
+    const now = summarizePlacementCounts(input.current);
+    const found = [];
+    const pair = { senderDomain: input.senderDomain, receiverProvider: input.receiverProvider };
+    if (base.settled >= PLACEMENT_SIGNAL_MIN_SAMPLE && now.settled >= PLACEMENT_SIGNAL_MIN_SAMPLE
+        && meets(base.inboxRate.value - now.inboxRate.value, PLACEMENT_SIGNAL_INBOX_DROP)) {
+        found.push({ transition: "inbox_rate_drop", ...pair, baseline: base.inboxRate, current: now.inboxRate,
+            delta: round4(now.inboxRate.value - base.inboxRate.value), threshold: PLACEMENT_SIGNAL_INBOX_DROP, minSample: PLACEMENT_SIGNAL_MIN_SAMPLE });
+    }
+    if (base.primaryRate.denominator >= PLACEMENT_SIGNAL_MIN_TAB_SAMPLE && now.primaryRate.denominator >= PLACEMENT_SIGNAL_MIN_TAB_SAMPLE
+        && meets(base.primaryRate.value - now.primaryRate.value, PLACEMENT_SIGNAL_TAB_SHIFT)
+        && meets(now.promotionsRate.value - base.promotionsRate.value, PLACEMENT_SIGNAL_TAB_SHIFT)) {
+        found.push({ transition: "primary_to_promotions", ...pair, baseline: base.primaryRate, current: now.primaryRate,
+            delta: round4(now.primaryRate.value - base.primaryRate.value), threshold: PLACEMENT_SIGNAL_TAB_SHIFT,
+            minSample: PLACEMENT_SIGNAL_MIN_TAB_SAMPLE, secondary: { baseline: base.promotionsRate, current: now.promotionsRate, delta: round4(now.promotionsRate.value - base.promotionsRate.value) } });
+    }
+    return found;
+}
+const PROVIDER_LABEL = { google: "Google", microsoft: "Microsoft", yahoo: "Yahoo", other: "other receivers", unknown: "unknown receivers" };
+const percent = (rate) => (rate.value === null ? "n/a" : `${Math.round(rate.value * 100)}%`);
+export function placementTransitionSummary(t) {
+    const where = `${t.senderDomain} at ${PROVIDER_LABEL[t.receiverProvider]}`;
+    return t.transition === "inbox_rate_drop"
+        ? `Inbox rate for ${where} fell from ${percent(t.baseline)} (n=${t.baseline.denominator}) to ${percent(t.current)} (n=${t.current.denominator}).`
+        : `Gmail Primary share for ${where} fell from ${percent(t.baseline)} to ${percent(t.current)} while Promotions rose from ${percent(t.secondary.baseline)} to ${percent(t.secondary.current)} (n=${t.baseline.denominator} → n=${t.current.denominator}).`;
+}