@oxygen-agent/cli 1.1014.1138 → 1.1014.1221

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

@@ -0,0 +1,334 @@
+import type { DeliverabilityFindingStatus, DeliverabilityRunStatus, PlacementReceiverProvider } from "./deliverability-checks.js";
+import { type CampaignOutcomes, type DeliverabilityCheckState, type PlacementEvidence } from "./deliverability-evidence.js";
+/**
+ * The deliverability evidence loop: a scheduled Workflow that reads the stored deliverability evidence
+ * (copy scores, placement observations, DNS/BIMI/tracking/blacklist findings, campaign outcomes) and
+ * turns threshold crossings into proposals. This module is the whole policy: pure, deterministic and
+ * free of I/O. It never sends email, never starts a copy test and never changes a sender; every proposal
+ * only recommends an action, and that action keeps its own preview and approval when a person takes it.
+ * Proposals are stored with the run (the review step's output), so every daily run completes and the
+ * next one reads what earlier runs raised.
+ */
+export declare const DELIVERABILITY_LOOP_TEMPLATE_ID = "deliverability-evidence-loop";
+/** The loop's two Workflow tools. `@oxygen/tools` registers these exact ids; the cooldown read finds earlier reviews by the second. */
+export declare const DELIVERABILITY_LOOP_COPY_SCORE_TOOL_ID = "oxygen.deliverability_copy_score";
+export declare const DELIVERABILITY_LOOP_REVIEW_TOOL_ID = "oxygen.deliverability_evidence_review";
+export type DeliverabilityLoopThresholds = {
+    /** Days in the current window; the previous window is the same length, immediately before it. */
+    windowDays: number;
+    /** Settled probes each window needs before an inbox-rate change is trusted. */
+    minSample: number;
+    /** Absolute inbox-rate fall (0.25 = 25 percentage points) that raises a proposal. */
+    inboxDrop: number;
+    /** Active copy variants scored and reviewed per cycle. */
+    maxCopies: number;
+    /** Sending domains reviewed per cycle. */
+    maxDomains: number;
+    /** A proposal an earlier live run of this Workflow raised is not raised again for this many days. */
+    cooldownDays: number;
+};
+export declare const DELIVERABILITY_LOOP_DEFAULTS: DeliverabilityLoopThresholds;
+/** Inclusive bounds per threshold; values outside them are refused, never clamped silently. */
+export declare const DELIVERABILITY_LOOP_LIMITS: Record<keyof DeliverabilityLoopThresholds, {
+    min: number;
+    max: number;
+    integer: boolean;
+}>;
+/** Request field per threshold (Workflow node params are snake_case). */
+export declare const DELIVERABILITY_LOOP_PARAM_NAMES: Record<keyof DeliverabilityLoopThresholds, string>;
+/** A workspace copy test holds at most this many messages (senders × receivers × variants). */
+export declare const DELIVERABILITY_LOOP_COPY_TEST_MAX_MESSAGES = 50;
+/** Receiver providers a workspace copy test can reach: this workspace's connected Google and Microsoft inboxes. */
+export declare const DELIVERABILITY_LOOP_COPY_TEST_PROVIDERS: readonly ["google", "microsoft"];
+export type DeliverabilityLoopCopyTestProvider = (typeof DELIVERABILITY_LOOP_COPY_TEST_PROVIDERS)[number];
+export type DeliverabilityLoopThresholdIssue = {
+    field: string;
+    message: string;
+};
+/** Defaults under the supplied values; every supplied value must be a number inside its bounds. */
+export declare function resolveDeliverabilityLoopThresholds(input: Record<string, unknown>): {
+    thresholds: DeliverabilityLoopThresholds;
+    issues: DeliverabilityLoopThresholdIssue[];
+};
+/** One active email Sequence variant and its latest stored content score. */
+export type DeliverabilityLoopCopy = {
+    sequenceId: string;
+    sequenceName: string;
+    stepId: string;
+    stepIndex: number;
+    /** "A" is the step's base copy; "B", "C", … its variants (the workspace copy-test keys). */
+    variantKey: string;
+    fromAddress: string | null;
+    /**
+     * Domains this copy is sent from: the step's pinned inbox or sender profile, else the Sequence's
+     * sending pool. Null when the Sequence may send from any workspace inbox across several domains,
+     * so the copy cannot be tied to one domain.
+     */
+    senderDomains: string[] | null;
+    subject: string;
+    contentHash: string;
+    score: {
+        /** The newest stored content-score run with a score; null when this copy was never scored. */
+        runId: string | null;
+        scoredAt: string | null;
+        value: number | null;
+        requiredScore: number | null;
+        verdict: DeliverabilityFindingStatus;
+        /** Triggered rules that count against the copy, highest first. */
+        topRules: string[];
+        /** Status of the newest attempt when it is newer than the score above (for example a failed rescoring). */
+        latestAttempt: DeliverabilityRunStatus | null;
+    };
+};
+export type DeliverabilityLoopWindowEvidence = {
+    placement: PlacementEvidence;
+    byReceiverProvider: Array<{
+        receiverProvider: PlacementReceiverProvider;
+        placement: PlacementEvidence;
+    }>;
+    campaign: CampaignOutcomes | null;
+    /** Copy hashes probed from this domain in the window, most probes first. */
+    contentHashes: string[];
+};
+export type DeliverabilityLoopDomain = {
+    domain: string;
+    current: DeliverabilityLoopWindowEvidence;
+    previous: DeliverabilityLoopWindowEvidence;
+    /** Latest dns_auth, bimi and blacklist state of the domain. */
+    checks: DeliverabilityCheckState[];
+};
+export type DeliverabilityLoopTrackingHost = {
+    host: string;
+    status: string;
+    state: DeliverabilityCheckState;
+};
+export type DeliverabilityLoopListing = {
+    subject: string;
+    check: string;
+    zone: string;
+    listedAt: string;
+    runId: string;
+};
+export type DeliverabilityLoopSnapshot = {
+    now: string;
+    window: {
+        currentSince: string;
+        previousSince: string;
+        until: string;
+    };
+    copies: DeliverabilityLoopCopy[];
+    copiesTotal: number;
+    domains: DeliverabilityLoopDomain[];
+    domainsTotal: number;
+    tracking: DeliverabilityLoopTrackingHost[];
+    /** Listings that started in the current window (the previous answer for that zone was not listed, or there was none). */
+    newListings: DeliverabilityLoopListing[];
+    /**
+     * Subjects listed on at least one zone by the latest ANSWERED (pass or fail) result for that zone, so
+     * a later refused or timed-out check never hides a listing. `runId`/`checkedAt` name the newest run
+     * that answered a listed zone.
+     */
+    activeListings: Array<{
+        subject: string;
+        checks: string[];
+        runId: string;
+        checkedAt: string;
+    }>;
+    /** Subjects of every kind (sending, tracking and link domains) whose newest blacklist run got no usable answer. */
+    unansweredBlacklist: Array<{
+        subject: string;
+        state: DeliverabilityRunStatus;
+        runId: string;
+        checkedAt: string;
+    }>;
+    /** Proposal fingerprints earlier live runs of this Workflow raised within the cooldown. */
+    recentFingerprints: string[];
+};
+export declare const DELIVERABILITY_LOOP_PROPOSAL_KINDS: readonly ["placement_drop", "dns_auth_failure", "tracking_dns_failure", "new_listing", "high_content_score"];
+export type DeliverabilityLoopProposalKind = (typeof DELIVERABILITY_LOOP_PROPOSAL_KINDS)[number];
+type CopyRef = {
+    sequence_id: string;
+    sequence_name: string;
+    step_id: string;
+    step_index: number;
+    variant_key: string;
+    subject: string;
+    content_hash: string;
+};
+/**
+ * How big a recommended workspace copy test is. The test sends one message per sender × receiver ×
+ * variant, so the person chooses senders and receivers to reach `min_messages`; it never exceeds
+ * `max_messages`.
+ */
+export type DeliverabilityLoopCopyTestSize = {
+    variants: number;
+    min_messages: number;
+    max_messages: number;
+    messages: "senders × receivers × variants";
+};
+export type DeliverabilityLoopAction = {
+    type: "run_workspace_copy_test";
+    /** Never started by this Workflow; a person previews and approves it. */
+    requires_human_approval: true;
+    copy: CopyRef | null;
+    variants: string[];
+    sender_domain: string;
+    receiver_provider: DeliverabilityLoopCopyTestProvider;
+    size: DeliverabilityLoopCopyTestSize;
+    next_steps: string[];
+} | {
+    /** A drop at a receiver no workspace copy test reaches (Yahoo, other providers). */
+    type: "review_placement";
+    requires_human_approval: true;
+    sender_domain: string;
+    receiver_provider: PlacementReceiverProvider;
+    next_steps: string[];
+} | {
+    type: "fix_dns";
+    requires_human_approval: true;
+    domain: string;
+    failing_checks: string[];
+    next_steps: string[];
+} | {
+    type: "fix_tracking_host";
+    requires_human_approval: true;
+    host: string;
+    failing_checks: string[];
+    next_steps: string[];
+} | {
+    type: "investigate_listing";
+    requires_human_approval: true;
+    subject: string;
+    checks: string[];
+    next_steps: string[];
+} | {
+    type: "revise_copy";
+    requires_human_approval: true;
+    copy: CopyRef;
+    copy_test: {
+        variants: string[];
+        size: DeliverabilityLoopCopyTestSize;
+    };
+    next_steps: string[];
+};
+export type DeliverabilityLoopProposal = {
+    fingerprint: string;
+    kind: DeliverabilityLoopProposalKind;
+    severity: "high" | "medium";
+    title: string;
+    evidence: Record<string, unknown>;
+    recommended_action: DeliverabilityLoopAction;
+};
+export type DeliverabilityLoopPlacementPair = {
+    sender_domain: string;
+    receiver_provider: PlacementReceiverProvider;
+    previous: {
+        settled: number;
+        inbox_rate: number | null;
+    };
+    current: {
+        settled: number;
+        inbox_rate: number | null;
+    };
+    delta: number | null;
+    verdict: "drop" | "steady" | "low_sample";
+};
+export type DeliverabilityLoopReport = {
+    status: "clear" | "attention";
+    summary: string;
+    window: {
+        current_since: string;
+        previous_since: string;
+        until: string;
+        days: number;
+    };
+    thresholds: {
+        window_days: number;
+        min_sample: number;
+        inbox_drop: number;
+        max_copies: number;
+        max_domains: number;
+        cooldown_days: number;
+    };
+    placement: {
+        pairs: DeliverabilityLoopPlacementPair[];
+        drops: number;
+        low_sample: number;
+    };
+    campaign: Array<{
+        sender_domain: string;
+        current: CampaignOutcomes | null;
+        previous: CampaignOutcomes | null;
+    }>;
+    domains: {
+        reviewed: number;
+        total: number;
+        truncated: boolean;
+        checks: Array<{
+            domain: string;
+            dns_auth: string;
+            bimi: string;
+            blacklist: string;
+            failing: string[];
+            warning: string[];
+        }>;
+    };
+    tracking: Array<{
+        host: string;
+        status: string;
+        check: string;
+        failing: string[];
+    }>;
+    listings: {
+        new: DeliverabilityLoopListing[];
+        active: Array<{
+            subject: string;
+            checks: string[];
+            checked_at: string;
+        }>;
+        unanswered: Array<{
+            subject: string;
+            state: DeliverabilityRunStatus;
+            checked_at: string;
+        }>;
+    };
+    copy: {
+        reviewed: number;
+        total: number;
+        truncated: boolean;
+        verdicts: Record<DeliverabilityFindingStatus, number>;
+        items: Array<{
+            sequence_id: string;
+            sequence_name: string;
+            step_index: number;
+            variant_key: string;
+            content_hash: string;
+            score: number | null;
+            required_score: number | null;
+            verdict: DeliverabilityFindingStatus;
+            scored_at: string | null;
+        }>;
+    };
+    evidence_gaps: string[];
+    proposals: DeliverabilityLoopProposal[];
+    proposal_count: number;
+    proposal_fingerprints: string[];
+    /** Crossed thresholds already raised by this Workflow within the cooldown; listed, not raised again. */
+    suppressed_proposals: Array<{
+        fingerprint: string;
+        kind: DeliverabilityLoopProposalKind;
+        title: string;
+    }>;
+    /** What this Workflow never does, stated on every run. */
+    effects: {
+        sends_email: false;
+        starts_copy_test: false;
+        changes_senders: false;
+    };
+};
+/**
+ * Turn one evidence snapshot into the run's report: a concise summary, the evidence behind it and a
+ * proposal per crossed threshold. Deterministic for a given snapshot and thresholds.
+ */
+export declare function evaluateDeliverabilityLoop(snapshot: DeliverabilityLoopSnapshot, t?: DeliverabilityLoopThresholds): DeliverabilityLoopReport;
+export {};

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

@@ -0,0 +1,312 @@
+import { PLACEMENT_SIGNAL_INBOX_DROP, PLACEMENT_SIGNAL_MIN_SAMPLE, } from "./deliverability-evidence.js";
+/**
+ * The deliverability evidence loop: a scheduled Workflow that reads the stored deliverability evidence
+ * (copy scores, placement observations, DNS/BIMI/tracking/blacklist findings, campaign outcomes) and
+ * turns threshold crossings into proposals. This module is the whole policy: pure, deterministic and
+ * free of I/O. It never sends email, never starts a copy test and never changes a sender; every proposal
+ * only recommends an action, and that action keeps its own preview and approval when a person takes it.
+ * Proposals are stored with the run (the review step's output), so every daily run completes and the
+ * next one reads what earlier runs raised.
+ */
+export const DELIVERABILITY_LOOP_TEMPLATE_ID = "deliverability-evidence-loop";
+/** The loop's two Workflow tools. `@oxygen/tools` registers these exact ids; the cooldown read finds earlier reviews by the second. */
+export const DELIVERABILITY_LOOP_COPY_SCORE_TOOL_ID = "oxygen.deliverability_copy_score";
+export const DELIVERABILITY_LOOP_REVIEW_TOOL_ID = "oxygen.deliverability_evidence_review";
+export const DELIVERABILITY_LOOP_DEFAULTS = {
+    windowDays: 7,
+    minSample: PLACEMENT_SIGNAL_MIN_SAMPLE,
+    inboxDrop: PLACEMENT_SIGNAL_INBOX_DROP,
+    maxCopies: 20,
+    maxDomains: 20,
+    cooldownDays: 7,
+};
+/** Inclusive bounds per threshold; values outside them are refused, never clamped silently. */
+export const DELIVERABILITY_LOOP_LIMITS = {
+    windowDays: { min: 3, max: 14, integer: true },
+    minSample: { min: 4, max: 200, integer: true },
+    inboxDrop: { min: 0.05, max: 0.9, integer: false },
+    // Bounded so a cycle of unresponsive scorer calls (10 s each, 4 at a time) stays inside one Workflow step's time budget.
+    maxCopies: { min: 1, max: 30, integer: true },
+    maxDomains: { min: 1, max: 50, integer: true },
+    cooldownDays: { min: 1, max: 30, integer: true },
+};
+/** Request field per threshold (Workflow node params are snake_case). */
+export const DELIVERABILITY_LOOP_PARAM_NAMES = {
+    windowDays: "window_days",
+    minSample: "min_sample",
+    inboxDrop: "inbox_drop",
+    maxCopies: "max_copies",
+    maxDomains: "max_domains",
+    cooldownDays: "cooldown_days",
+};
+/** A workspace copy test holds at most this many messages (senders × receivers × variants). */
+export const DELIVERABILITY_LOOP_COPY_TEST_MAX_MESSAGES = 50;
+/** Receiver providers a workspace copy test can reach: this workspace's connected Google and Microsoft inboxes. */
+export const DELIVERABILITY_LOOP_COPY_TEST_PROVIDERS = ["google", "microsoft"];
+/** Defaults under the supplied values; every supplied value must be a number inside its bounds. */
+export function resolveDeliverabilityLoopThresholds(input) {
+    const thresholds = { ...DELIVERABILITY_LOOP_DEFAULTS };
+    const issues = [];
+    for (const key of Object.keys(DELIVERABILITY_LOOP_DEFAULTS)) {
+        const field = DELIVERABILITY_LOOP_PARAM_NAMES[key];
+        const value = input[field];
+        if (value === undefined || value === null)
+            continue;
+        const limit = DELIVERABILITY_LOOP_LIMITS[key];
+        if (typeof value !== "number" || !Number.isFinite(value) || value < limit.min || value > limit.max || (limit.integer && !Number.isInteger(value))) {
+            issues.push({ field, message: `${field} must be ${limit.integer ? "an integer" : "a number"} from ${limit.min} to ${limit.max}.` });
+            continue;
+        }
+        thresholds[key] = value;
+    }
+    return { thresholds, issues };
+}
+export const DELIVERABILITY_LOOP_PROPOSAL_KINDS = ["placement_drop", "dns_auth_failure", "tracking_dns_failure", "new_listing", "high_content_score"];
+const PROVIDER_LABEL = { google: "Google", microsoft: "Microsoft", yahoo: "Yahoo", other: "other providers", unknown: "unknown providers" };
+const percent = (value) => (value === null ? "n/a" : `${Math.round(value * 100)}%`);
+const round4 = (value) => Math.round(value * 10_000) / 10_000;
+const plural = (count, one, many = `${one}s`) => `${count} ${count === 1 ? one : many}`;
+const copyRef = (copy) => ({
+    sequence_id: copy.sequenceId, sequence_name: copy.sequenceName, step_id: copy.stepId, step_index: copy.stepIndex,
+    variant_key: copy.variantKey, subject: copy.subject, content_hash: copy.contentHash,
+});
+const copyTestCommand = (copy) => `oxygen deliverability workspace-test copy ${copy.sequence_id} --step-index ${copy.step_index} --json`;
+const copyTestSteps = (copy) => [
+    ...(copy ? [`Read the exact copy: ${copyTestCommand(copy)}`] : ["Choose the copy to test; no active Sequence copy is known to be sent from this domain."]),
+    "Preview the workspace copy test (sends nothing, 0 credits), review every sender, receiver and copy, then approve it explicitly.",
+];
+const copyTestSize = (variants, minMessages) => ({
+    variants, min_messages: Math.min(minMessages, DELIVERABILITY_LOOP_COPY_TEST_MAX_MESSAGES),
+    max_messages: DELIVERABILITY_LOOP_COPY_TEST_MAX_MESSAGES, messages: "senders × receivers × variants",
+});
+const sizeText = (size) => `senders × receivers × ${plural(size.variants, "variant")} reaches at least ${size.min_messages} messages (one test sends at most ${size.max_messages})`;
+const testableProvider = (provider) => DELIVERABILITY_LOOP_COPY_TEST_PROVIDERS.includes(provider);
+/**
+ * The copy most likely behind a domain's placement: probed from it in the window, else active copy whose
+ * sender is known to be on this domain. Copy that may go out from any workspace inbox is never guessed.
+ */
+function copyForDomain(copies, domain) {
+    for (const hash of domain.current.contentHashes) {
+        const probed = copies.find((copy) => copy.contentHash === hash);
+        if (probed)
+            return probed;
+    }
+    return copies.find((copy) => copy.senderDomains?.includes(domain.domain)) ?? null;
+}
+function placementPairs(domain, t) {
+    const providers = new Set();
+    for (const entry of [...domain.previous.byReceiverProvider, ...domain.current.byReceiverProvider]) {
+        if (entry.receiverProvider !== "unknown")
+            providers.add(entry.receiverProvider);
+    }
+    return [...providers].sort().map((provider) => {
+        const before = domain.previous.byReceiverProvider.find((entry) => entry.receiverProvider === provider)?.placement;
+        const now = domain.current.byReceiverProvider.find((entry) => entry.receiverProvider === provider)?.placement;
+        const previous = { settled: before?.settled ?? 0, inbox_rate: before?.inboxRate.value ?? null };
+        const current = { settled: now?.settled ?? 0, inbox_rate: now?.inboxRate.value ?? null };
+        const sampled = previous.settled >= t.minSample && current.settled >= t.minSample;
+        const delta = previous.inbox_rate !== null && current.inbox_rate !== null ? round4(current.inbox_rate - previous.inbox_rate) : null;
+        // Rates are rounded to 4 places, so a threshold met exactly must not miss on float noise.
+        const verdict = !sampled ? "low_sample" : delta !== null && -delta >= t.inboxDrop - 1e-9 ? "drop" : "steady";
+        return { sender_domain: domain.domain, receiver_provider: provider, previous, current, delta, verdict };
+    });
+}
+const stateLabel = (state) => state?.state ?? "never_run";
+const blacklistGap = (subject) => `${subject}: the latest blacklist check got no usable answer; its listing state is unknown, not clean.`;
+/**
+ * Turn one evidence snapshot into the run's report: a concise summary, the evidence behind it and a
+ * proposal per crossed threshold. Deterministic for a given snapshot and thresholds.
+ */
+export function evaluateDeliverabilityLoop(snapshot, t = DELIVERABILITY_LOOP_DEFAULTS) {
+    const crossed = [];
+    const gaps = [];
+    const pairs = snapshot.domains.flatMap((domain) => placementPairs(domain, t));
+    for (const pair of pairs.filter((p) => p.verdict === "drop")) {
+        const domain = snapshot.domains.find((d) => d.domain === pair.sender_domain);
+        const label = PROVIDER_LABEL[pair.receiver_provider];
+        const provider = pair.receiver_provider;
+        let action;
+        if (testableProvider(provider)) {
+            const copy = copyForDomain(snapshot.copies, domain);
+            const ref = copy ? copyRef(copy) : null;
+            const size = copyTestSize(1, t.minSample);
+            action = {
+                type: "run_workspace_copy_test", requires_human_approval: true, copy: ref, variants: ref ? [ref.variant_key] : [],
+                sender_domain: pair.sender_domain, receiver_provider: provider, size,
+                next_steps: [
+                    ...copyTestSteps(ref),
+                    `Choose senders on ${pair.sender_domain} and connected ${label} receivers so ${sizeText(size)}, the minimum sample this drop was measured on.`,
+                    "Placement is directional evidence: do not pause or change senders on it alone.",
+                ],
+            };
+        }
+        else {
+            action = {
+                type: "review_placement", requires_human_approval: true, sender_domain: pair.sender_domain, receiver_provider: provider,
+                next_steps: [
+                    `A workspace copy test reaches only this workspace's connected Google and Microsoft receivers, so it cannot test ${label}.`,
+                    `Compare this run's placement evidence for ${pair.sender_domain} with its recent sends, copy changes and blacklist findings.`,
+                    "Placement is directional evidence: do not pause or change senders on it alone.",
+                ],
+            };
+        }
+        crossed.push({
+            fingerprint: `placement_drop:${pair.sender_domain}:${pair.receiver_provider}`,
+            kind: "placement_drop",
+            severity: "high",
+            title: `Inbox rate for ${pair.sender_domain} at ${label} fell from ${percent(pair.previous.inbox_rate)} to ${percent(pair.current.inbox_rate)}`,
+            evidence: { ...pair, min_sample: t.minSample, threshold: t.inboxDrop, denominator_of: "settled_probes" },
+            recommended_action: action,
+        });
+    }
+    const lowSample = pairs.filter((p) => p.verdict === "low_sample").length;
+    if (!pairs.some((p) => p.previous.settled + p.current.settled > 0))
+        gaps.push("No placement observations in either window; run an approved copy test to collect some.");
+    const domainChecks = snapshot.domains.map((domain) => {
+        const state = (kind) => domain.checks.find((check) => check.kind === kind);
+        const dns = state("dns_auth");
+        const failing = domain.checks.flatMap((check) => check.failing);
+        const warning = domain.checks.flatMap((check) => check.warning);
+        const dnsFailing = dns?.failing ?? [];
+        if (dnsFailing.length) {
+            crossed.push({
+                fingerprint: `dns_auth_failure:${domain.domain}:${[...dnsFailing].sort().join(",")}`,
+                kind: "dns_auth_failure",
+                severity: "high",
+                title: `${domain.domain} fails ${plural(dnsFailing.length, "DNS authentication check")}`,
+                evidence: { domain: domain.domain, failing_checks: dnsFailing, run_id: dns.runId, checked_at: dns.startedAt },
+                recommended_action: {
+                    type: "fix_dns", requires_human_approval: true, domain: domain.domain, failing_checks: dnsFailing,
+                    next_steps: [
+                        `Read the saved evidence behind this proposal: oxygen domains dns ${domain.domain} --cached --json`,
+                        `Check the live records again before changing anything: oxygen domains dns ${domain.domain} --deep --json`,
+                        "Correct the records at the DNS host; the daily check records the fix.",
+                    ],
+                },
+            });
+        }
+        if (!dns || dns.state === "never_run")
+            gaps.push(`${domain.domain}: DNS authentication has not been checked yet.`);
+        else if (dns.state === "failed" || dns.state === "unknown")
+            gaps.push(`${domain.domain}: the latest DNS authentication check could not read public DNS.`);
+        const blacklist = state("blacklist");
+        if (!blacklist || blacklist.state === "never_run")
+            gaps.push(`${domain.domain}: no blacklist check has run.`);
+        else if (blacklist.state === "unknown" || blacklist.state === "failed")
+            gaps.push(blacklistGap(domain.domain));
+        return { domain: domain.domain, dns_auth: stateLabel(dns), bimi: stateLabel(state("bimi")), blacklist: stateLabel(blacklist), failing, warning };
+    });
+    const tracking = snapshot.tracking.map((host) => {
+        if (host.state.failing.length) {
+            crossed.push({
+                fingerprint: `tracking_dns_failure:${host.host}:${[...host.state.failing].sort().join(",")}`,
+                kind: "tracking_dns_failure",
+                severity: "medium",
+                title: `Tracking host ${host.host} fails ${plural(host.state.failing.length, "check")}`,
+                evidence: { host: host.host, status: host.status, failing_checks: host.state.failing, run_id: host.state.runId, checked_at: host.state.startedAt },
+                recommended_action: {
+                    type: "fix_tracking_host", requires_human_approval: true, host: host.host, failing_checks: host.state.failing,
+                    next_steps: ["Point the host's CNAME at the tracking target shown in Settings, then wait for the daily verification."],
+                },
+            });
+        }
+        return { host: host.host, status: host.status, check: host.state.state, failing: host.state.failing };
+    });
+    for (const subject of snapshot.unansweredBlacklist)
+        gaps.push(blacklistGap(subject.subject));
+    const listingsBySubject = new Map();
+    for (const listing of snapshot.newListings)
+        listingsBySubject.set(listing.subject, [...(listingsBySubject.get(listing.subject) ?? []), listing]);
+    for (const [subject, listings] of [...listingsBySubject].sort(([a], [b]) => a.localeCompare(b))) {
+        const checks = [...new Set(listings.map((listing) => listing.check))].sort();
+        crossed.push({
+            fingerprint: `new_listing:${subject}:${checks.join(",")}`,
+            kind: "new_listing",
+            severity: "high",
+            title: `${subject} was newly listed on ${plural(checks.length, "blacklist zone")}`,
+            evidence: { subject, listings },
+            recommended_action: {
+                type: "investigate_listing", requires_human_approval: true, subject, checks,
+                next_steps: [
+                    "Compare the listing time with recent sends, new link domains and copy changes from this domain.",
+                    "Request delisting from the zone operator once the cause is fixed; the daily check records the delisting.",
+                ],
+            },
+        });
+    }
+    const verdicts = { pass: 0, warn: 0, fail: 0, unknown: 0 };
+    const proposedCopy = new Set();
+    for (const copy of snapshot.copies) {
+        verdicts[copy.score.verdict] += 1;
+        // Identical copy in several Sequences is one content hash, so one proposal (naming its first use).
+        if (copy.score.verdict !== "fail" || proposedCopy.has(copy.contentHash))
+            continue;
+        proposedCopy.add(copy.contentHash);
+        const ref = copyRef(copy);
+        const size = copyTestSize(2, 2 * t.minSample);
+        crossed.push({
+            fingerprint: `high_content_score:${copy.contentHash}`,
+            kind: "high_content_score",
+            severity: "medium",
+            title: `"${copy.sequenceName}" step ${copy.stepIndex + 1} variant ${copy.variantKey} scores ${copy.score.value ?? "n/a"} of ${copy.score.requiredScore ?? "n/a"}`,
+            evidence: { ...ref, score: copy.score.value, required_score: copy.score.requiredScore, top_rules: copy.score.topRules, run_id: copy.score.runId, scored_at: copy.score.scoredAt },
+            recommended_action: {
+                type: "revise_copy", requires_human_approval: true, copy: ref,
+                copy_test: { variants: [ref.variant_key, "revised"], size },
+                next_steps: [
+                    copy.score.topRules.length ? `Revise the copy that triggers ${copy.score.topRules.slice(0, 3).join(", ")}.` : "Revise the copy, then score it again.",
+                    `Optionally compare the current and revised copy in one approved workspace copy test where ${sizeText(size)}: ${copyTestCommand(ref)}`,
+                ],
+            },
+        });
+    }
+    if (snapshot.copies.length && snapshot.copies.every((copy) => copy.score.runId === null))
+        gaps.push("No active copy has a stored content score; copy scoring may be unavailable.");
+    else if (snapshot.copies.some((copy) => copy.score.latestAttempt === "failed"))
+        gaps.push("Copy scoring failed for some copy this cycle; the newest earlier score is shown.");
+    const recent = new Set(snapshot.recentFingerprints);
+    const proposals = crossed.filter((proposal) => !recent.has(proposal.fingerprint));
+    const suppressed = crossed.filter((proposal) => recent.has(proposal.fingerprint)).map(({ fingerprint, kind, title }) => ({ fingerprint, kind, title }));
+    const drops = pairs.filter((p) => p.verdict === "drop");
+    const dnsFailingDomains = domainChecks.filter((d) => snapshot.domains.find((x) => x.domain === d.domain).checks.some((c) => c.kind === "dns_auth" && c.failing.length));
+    const until = snapshot.window.until.slice(0, 10);
+    const lines = [
+        `Deliverability evidence for the ${t.windowDays} days to ${until}, compared with the ${t.windowDays} days before.`,
+        `Placement: ${plural(pairs.length, "sender domain × receiver pair")} compared; ${plural(drops.length, "inbox-rate drop")}${drops.length ? ` (${drops.map((p) => `${p.sender_domain} at ${PROVIDER_LABEL[p.receiver_provider]} ${percent(p.previous.inbox_rate)} → ${percent(p.current.inbox_rate)}, n=${p.previous.settled}/${p.current.settled}`).join("; ")})` : ""}; ${lowSample} below the ${t.minSample}-probe minimum.`,
+        `Authentication: ${dnsFailingDomains.length} of ${plural(snapshot.domains.length, "sending domain")} fail DNS checks${dnsFailingDomains.length ? ` (${dnsFailingDomains.map((d) => d.domain).join(", ")})` : ""}.`,
+        `Tracking: ${tracking.filter((h) => h.failing.length).length} of ${plural(tracking.length, "tracking host")} failing.`,
+        `Blacklists: ${plural(listingsBySubject.size, "subject")} newly listed; ${plural(snapshot.activeListings.length, "subject")} currently listed${snapshot.unansweredBlacklist.length ? `; ${plural(snapshot.unansweredBlacklist.length, "subject")} without a usable answer on the latest check` : ""}.`,
+        `Copy: ${plural(snapshot.copies.length, "active copy", "active copies")} reviewed; ${verdicts.fail} high, ${verdicts.warn} elevated, ${verdicts.unknown} unscored.`,
+        proposals.length
+            ? `${plural(proposals.length, "new proposal")}${suppressed.length ? `; ${suppressed.length} already raised within ${t.cooldownDays} days` : ""}. Each recommended action keeps its own preview and approval. Nothing was sent, tested or changed.`
+            : `No new proposal${suppressed.length ? ` (${suppressed.length} already raised within ${t.cooldownDays} days)` : ""}. Nothing was sent, tested or changed.`,
+    ];
+    return {
+        status: crossed.length ? "attention" : "clear",
+        summary: lines.join("\n"),
+        window: { current_since: snapshot.window.currentSince, previous_since: snapshot.window.previousSince, until: snapshot.window.until, days: t.windowDays },
+        thresholds: { window_days: t.windowDays, min_sample: t.minSample, inbox_drop: t.inboxDrop, max_copies: t.maxCopies, max_domains: t.maxDomains, cooldown_days: t.cooldownDays },
+        placement: { pairs, drops: drops.length, low_sample: lowSample },
+        campaign: snapshot.domains.map((domain) => ({ sender_domain: domain.domain, current: domain.current.campaign, previous: domain.previous.campaign })),
+        domains: { reviewed: snapshot.domains.length, total: snapshot.domainsTotal, truncated: snapshot.domainsTotal > snapshot.domains.length, checks: domainChecks },
+        tracking,
+        listings: {
+            new: snapshot.newListings,
+            active: snapshot.activeListings.map(({ subject, checks, checkedAt }) => ({ subject, checks, checked_at: checkedAt })),
+            unanswered: snapshot.unansweredBlacklist.map(({ subject, state, checkedAt }) => ({ subject, state, checked_at: checkedAt })),
+        },
+        copy: {
+            reviewed: snapshot.copies.length, total: snapshot.copiesTotal, truncated: snapshot.copiesTotal > snapshot.copies.length, verdicts,
+            items: snapshot.copies.map((copy) => ({
+                sequence_id: copy.sequenceId, sequence_name: copy.sequenceName, step_index: copy.stepIndex, variant_key: copy.variantKey, content_hash: copy.contentHash,
+                score: copy.score.value, required_score: copy.score.requiredScore, verdict: copy.score.verdict, scored_at: copy.score.scoredAt,
+            })),
+        },
+        evidence_gaps: [...new Set(gaps)],
+        proposals,
+        proposal_count: proposals.length,
+        proposal_fingerprints: proposals.map((proposal) => proposal.fingerprint),
+        suppressed_proposals: suppressed,
+        effects: { sends_email: false, starts_copy_test: false, changes_senders: false },
+    };
+}