@oxygen-agent/cli 1.1010.650 → 1.1010.905

package/node_modules/@oxygen/shared/dist/cost-estimate.js

@@ -0,0 +1,361 @@
+/**
+ * The scenario cost estimator behind `POST /api/cli/billing/estimate`
+ * (`oxygen billing estimate`, MCP `oxygen_billing_estimate`, Settings → Plan
+ * limits → Estimate a month). OXP-43.33.
+ *
+ * A founder asks "2,000 leads a month, work email on each, a 3-step email and
+ * LinkedIn sequence from 2 mailboxes and 1 LinkedIn account: what does that
+ * cost, and does anything run out?". Before this, an agent answered it by
+ * stitching six reads together by hand (blind baseline 2026-09-26, finding 9).
+ *
+ * Pure: the route resolves every price from the live pricing book, the
+ * enrichment catalog and the sending limits the send path enforces, and hands
+ * them in as a price sheet. Nothing here knows a price, so the estimate can
+ * never quote a number the product does not charge.
+ *
+ * Three things are kept apart on purpose, because they are paid differently:
+ *   - credits that recur every month (sender reservations, enrichment), which
+ *     size the plan;
+ *   - dollars that recur on a card (sending seats while seats are sold), which a
+ *     plan's credits never pay for;
+ *   - sending itself, which is free and is bounded by per-account limits, not by
+ *     money.
+ */
+export const COST_ESTIMATE_BOUNDS = {
+    maxLeadsPerMonth: 10_000_000,
+    maxStepsPerChannel: 20,
+    maxSendersPerKind: 1_000,
+    maxEnrichments: 12,
+};
+function round2(value) {
+    return Math.round((value + Number.EPSILON) * 100) / 100;
+}
+function whole(value) {
+    return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+function formatInt(value) {
+    return Math.round(value).toLocaleString("en-US");
+}
+function formatUsd(value) {
+    return `$${value.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+function senderLine(input) {
+    const { price, quantity } = input;
+    if (price.billedAs === "usd") {
+        const usd = round2((quantity * price.usdCentsPerMonth) / 100);
+        return {
+            key: input.key,
+            group: "senders",
+            label: input.label,
+            quantity,
+            unit: input.unit,
+            billed_as: "usd",
+            unit_credits: 0,
+            worst_case_unit_credits: 0,
+            credits_per_month: 0,
+            worst_case_credits_per_month: 0,
+            usd_per_month: usd,
+            note: `${formatUsd(price.usdCentsPerMonth / 100)} per ${input.unit} a month, billed in dollars as a sending seat; a plan's credits do not pay for it. ${input.note}`,
+        };
+    }
+    const unit = price.creditsPerMonth;
+    const credits = unit === null ? null : round2(quantity * unit);
+    const scheduled = price.scheduledCreditsPerMonth;
+    return {
+        key: input.key,
+        group: "senders",
+        label: input.label,
+        quantity,
+        unit: input.unit,
+        billed_as: "credits",
+        unit_credits: unit,
+        worst_case_unit_credits: unit,
+        credits_per_month: credits,
+        worst_case_credits_per_month: credits,
+        usd_per_month: credits === null ? null : round2(credits / input.creditsPerUsd),
+        ...(scheduled !== undefined && scheduled !== unit ? { scheduled_unit_credits: scheduled } : {}),
+        note: unit === null
+            ? `No monthly price is in force for this ${input.unit} yet, so nothing is reserved. ${input.note}`
+            : `${formatInt(unit)} credits per ${input.unit} a month, reserved from your balance on the day it connects. ${input.note}`,
+    };
+}
+function planOutcome(rung, credits, usdSeats, sheet) {
+    const shortfall = Math.max(0, Math.ceil(credits - rung.monthlyCredits));
+    // The amount `billing topup` actually sells: whole 100-credit steps, never
+    // below the smallest pack. Above 100,000 it takes more than one checkout.
+    const topupCredits = shortfall === 0
+        ? 0
+        : Math.max(sheet.topupMinCredits, Math.ceil(shortfall / sheet.topupStepCredits) * sheet.topupStepCredits);
+    const topupUsd = round2((topupCredits / 100) * (sheet.topupUsdCentsPer100 / 100));
+    const price = rung.monthlyPriceCents === null ? null : rung.monthlyPriceCents / 100;
+    return {
+        plan_key: rung.planKey,
+        label: rung.label,
+        monthly_price_usd: price,
+        monthly_credits: rung.monthlyCredits,
+        covered: shortfall === 0,
+        shortfall_credits: shortfall,
+        topup_credits: topupCredits,
+        topup_usd: topupUsd,
+        monthly_usd: price === null ? null : round2(price + topupUsd + usdSeats),
+    };
+}
+/** The cheapest monthly bill: plan plus top-ups, the smallest plan that covers winning a tie. */
+function cheapestRung(credits, usdSeats, sheet) {
+    let best = null;
+    for (const rung of sheet.rungs) {
+        if (rung.monthlyPriceCents === null)
+            continue;
+        const outcome = planOutcome(rung, credits, usdSeats, sheet);
+        if (best === null || (outcome.monthly_usd ?? Infinity) < (best.monthly_usd ?? Infinity))
+            best = outcome;
+    }
+    return best;
+}
+function rampFirstMonthCapacity(sheet) {
+    const { emailRamp, emailPerMailboxPerDay, sendingDaysPerMonth } = sheet.sending;
+    let total = 0;
+    for (let day = 1; day <= sendingDaysPerMonth; day += 1) {
+        const tier = emailRamp.find((step) => day <= step.throughDay);
+        total += tier ? Math.min(tier.perDay, emailPerMailboxPerDay) : emailPerMailboxPerDay;
+    }
+    return total;
+}
+function limitRow(input) {
+    const capacity = input.senders * input.perSender;
+    const sendersNeeded = input.needed === 0 || input.perSender <= 0 ? 0 : Math.ceil(input.needed / input.perSender);
+    const hit = input.needed > capacity;
+    const note = input.needed === 0
+        ? "Not used by this scenario."
+        : hit
+            ? `${formatInt(input.needed)} ${input.unit} a month needs ${formatInt(sendersNeeded)}; you entered ${formatInt(input.senders)}. Each sends ${formatInt(input.perSender)} a month (${input.bindingLimit}). ${input.addWith}`
+            : `${formatInt(input.needed)} of ${formatInt(capacity)} ${input.unit} a month (${input.bindingLimit} each).`;
+    return {
+        key: input.key,
+        label: input.label,
+        needed_per_month: input.needed,
+        senders: input.senders,
+        per_sender_per_month: input.perSender,
+        binding_limit: input.bindingLimit,
+        capacity_per_month: capacity,
+        first_month_capacity: input.firstMonthPerSender === null ? null : input.senders * input.firstMonthPerSender,
+        senders_needed: sendersNeeded,
+        hit,
+        note,
+    };
+}
+/** Clamp a scenario into the accepted bounds: whole, non-negative numbers. */
+export function normalizeCostEstimateScenario(scenario) {
+    const bound = (value, max) => Math.min(max, whole(value));
+    return {
+        leadsPerMonth: bound(scenario.leadsPerMonth, COST_ESTIMATE_BOUNDS.maxLeadsPerMonth),
+        enrichmentIds: [...new Set(scenario.enrichmentIds)].slice(0, COST_ESTIMATE_BOUNDS.maxEnrichments),
+        emailSteps: bound(scenario.emailSteps, COST_ESTIMATE_BOUNDS.maxStepsPerChannel),
+        linkedinSteps: bound(scenario.linkedinSteps, COST_ESTIMATE_BOUNDS.maxStepsPerChannel),
+        mailboxes: bound(scenario.mailboxes, COST_ESTIMATE_BOUNDS.maxSendersPerKind),
+        managedMailboxes: bound(scenario.managedMailboxes, COST_ESTIMATE_BOUNDS.maxSendersPerKind),
+        linkedinAccounts: bound(scenario.linkedinAccounts, COST_ESTIMATE_BOUNDS.maxSendersPerKind),
+    };
+}
+export function estimateScenarioCost(rawScenario, sheet) {
+    const scenario = normalizeCostEstimateScenario(rawScenario);
+    const leads = scenario.leadsPerMonth;
+    const lines = [];
+    const warnings = [];
+    for (const enrichment of sheet.enrichments) {
+        const expected = enrichment.expectedCreditsPerRow;
+        const worst = enrichment.worstCaseCreditsPerRow ?? expected;
+        const credits = expected === null ? null : round2(leads * expected);
+        const worstCredits = worst === null ? null : round2(leads * worst);
+        if (enrichment.kind === "unavailable" || expected === null) {
+            warnings.push(`${enrichment.label} has no per-row estimate, so it is not in the totals. Price it with a one-row dry run.`);
+        }
+        lines.push({
+            key: `enrichment.${enrichment.id}`,
+            group: "enrichment",
+            label: enrichment.label,
+            quantity: leads,
+            unit: "row",
+            billed_as: "credits",
+            unit_credits: expected,
+            worst_case_unit_credits: worst,
+            credits_per_month: credits,
+            worst_case_credits_per_month: worstCredits,
+            usd_per_month: credits === null ? null : round2(credits / sheet.creditsPerUsd),
+            note: enrichment.kind === "estimated"
+                ? `Billed only when a provider finds a result${enrichment.hitRatesAssumed ? "; the expected figure uses assumed hit rates" : ""}. Up to ${worst === null ? "an unknown amount" : `${round2(worst)} credits`} a row if the dearest provider answers every row.`
+                : enrichment.kind === "fixed"
+                    ? "The same price on every row."
+                    : "No estimate available.",
+        });
+    }
+    const mailboxNote = "Warm-up is included.";
+    if (scenario.mailboxes > 0) {
+        lines.push(senderLine({
+            key: "senders.mailbox",
+            label: "Connected mailboxes",
+            quantity: scenario.mailboxes,
+            unit: "mailbox",
+            price: sheet.senders.mailbox,
+            creditsPerUsd: sheet.creditsPerUsd,
+            note: mailboxNote,
+        }));
+    }
+    if (scenario.managedMailboxes > 0) {
+        lines.push(senderLine({
+            key: "senders.managed_mailbox",
+            label: "Mailboxes bought from OXYGEN",
+            quantity: scenario.managedMailboxes,
+            unit: "mailbox",
+            price: sheet.senders.managedMailbox,
+            creditsPerUsd: sheet.creditsPerUsd,
+            note: "Mailbox, connection and warm-up in one price; the sending domain is bought separately, once a year.",
+        }));
+    }
+    if (scenario.linkedinAccounts > 0) {
+        lines.push(senderLine({
+            key: "senders.linkedin_account",
+            label: "LinkedIn accounts",
+            quantity: scenario.linkedinAccounts,
+            unit: "account",
+            price: sheet.senders.linkedinAccount,
+            creditsPerUsd: sheet.creditsPerUsd,
+            note: "Invites, messages and every other LinkedIn action cost 0 credits.",
+        }));
+    }
+    const emails = leads * scenario.emailSteps;
+    const linkedinActions = leads * scenario.linkedinSteps;
+    for (const [key, label, quantity] of [
+        ["sending.email", "Emails sent", emails],
+        ["sending.linkedin", "LinkedIn invites and messages", linkedinActions],
+    ]) {
+        if (quantity === 0)
+            continue;
+        lines.push({
+            key,
+            group: "sending",
+            label,
+            quantity,
+            unit: "message",
+            billed_as: "free",
+            unit_credits: 0,
+            worst_case_unit_credits: 0,
+            credits_per_month: 0,
+            worst_case_credits_per_month: 0,
+            usd_per_month: 0,
+            note: "Sending costs 0 credits; the limits below bound how fast it goes.",
+        });
+    }
+    const sum = (pick, filter) => round2(lines.filter(filter).reduce((total, line) => total + (pick(line) ?? 0), 0));
+    const fixed = sum((line) => line.credits_per_month, (line) => line.group === "senders" && line.billed_as === "credits");
+    const flexible = sum((line) => line.credits_per_month, (line) => line.group === "enrichment");
+    const flexibleWorst = sum((line) => line.worst_case_credits_per_month, (line) => line.group === "enrichment");
+    const usdSeats = sum((line) => line.usd_per_month, (line) => line.billed_as === "usd");
+    const unpriced = lines
+        .filter((line) => line.billed_as === "credits" && line.credits_per_month === null)
+        .map((line) => line.key);
+    for (const line of lines) {
+        if (line.group === "senders" && line.billed_as === "credits" && line.credits_per_month === null) {
+            warnings.push(`${line.label} have no monthly price in force yet, so the estimate reserves nothing for them.`);
+        }
+    }
+    const credits = round2(fixed + flexible);
+    const worstCredits = round2(fixed + flexibleWorst);
+    const planFit = sheet.comparePlan
+        ? {
+            expected: planOutcome(sheet.comparePlan, credits, usdSeats, sheet),
+            worst_case: planOutcome(sheet.comparePlan, worstCredits, usdSeats, sheet),
+        }
+        : null;
+    const recommendedExpected = cheapestRung(credits, usdSeats, sheet);
+    const recommendedWorst = cheapestRung(worstCredits, usdSeats, sheet);
+    const recommended = recommendedExpected && recommendedWorst
+        ? { expected: recommendedExpected, worst_case: recommendedWorst }
+        : null;
+    const { sending } = sheet;
+    const invitesByWeek = Math.floor((sending.linkedinInvitesPerWeek * 52) / 12);
+    const invitesByDay = sending.linkedinInvitesPerDay * sending.sendingDaysPerMonth;
+    const inviteCapacity = Math.min(invitesByWeek, invitesByDay);
+    const inviteBinding = invitesByWeek <= invitesByDay
+        ? `${formatInt(sending.linkedinInvitesPerWeek)} invites a week`
+        : `${formatInt(sending.linkedinInvitesPerDay)} invites a day`;
+    const totalMailboxes = scenario.mailboxes + scenario.managedMailboxes;
+    const limits = [
+        limitRow({
+            key: "email_per_mailbox",
+            label: "Emails per mailbox",
+            needed: emails,
+            senders: totalMailboxes,
+            perSender: sending.emailPerMailboxPerDay * sending.sendingDaysPerMonth,
+            firstMonthPerSender: rampFirstMonthCapacity(sheet),
+            bindingLimit: `${formatInt(sending.emailPerMailboxPerDay)} emails a day`,
+            unit: "emails",
+            addWith: "Add mailboxes, or spread the leads over more months.",
+        }),
+        limitRow({
+            key: "linkedin_invites_per_account",
+            label: "LinkedIn invites per account",
+            needed: scenario.linkedinSteps > 0 ? leads : 0,
+            senders: scenario.linkedinAccounts,
+            perSender: inviteCapacity,
+            firstMonthPerSender: null,
+            bindingLimit: inviteBinding,
+            unit: "invites",
+            addWith: "Connect more LinkedIn accounts, or spread the leads over more months.",
+        }),
+        limitRow({
+            key: "linkedin_messages_per_account",
+            label: "LinkedIn messages per account",
+            needed: leads * Math.max(0, scenario.linkedinSteps - 1),
+            senders: scenario.linkedinAccounts,
+            perSender: sending.linkedinMessagesPerDay * sending.sendingDaysPerMonth,
+            firstMonthPerSender: null,
+            bindingLimit: `${formatInt(sending.linkedinMessagesPerDay)} messages a day`,
+            unit: "messages",
+            addWith: "Connect more LinkedIn accounts, or spread the leads over more months.",
+        }),
+    ].filter((row) => row.needed_per_month > 0);
+    const limitsHit = limits.filter((row) => row.hit).map((row) => row.key);
+    const assumptions = [
+        "Every lead is already in a table and goes through each enrichment and every sequence step. Finding new leads is priced separately.",
+        `Sending limits use ${sending.sendingDaysPerMonth} sending days a month and the defaults for a newly connected account (a sender you already run may be set lower): ${sending.emailPerMailboxPerDay} emails a mailbox a day, ${sending.linkedinInvitesPerDay} LinkedIn invites a day and ${sending.linkedinInvitesPerWeek} a week, ${sending.linkedinMessagesPerDay} LinkedIn messages a day.`,
+        "The first LinkedIn step is a connection invite and each later step a message to every lead, so the message count is an upper bound: only accepted invites receive messages.",
+        "While senders are paid as sending seats (sender_billing: sending_seats) they reserve no credits; once seats are retired each connected sender reserves its monthly price in credits instead, never both.",
+        `Credits are shown at face value, ${formatInt(sheet.creditsPerUsd)} credits to $1; top-ups cost ${formatUsd(sheet.topupUsdCentsPer100 / 100)} per 100 credits.`,
+    ];
+    if (totalMailboxes > 0 && emails > 0) {
+        const ramp = sending.emailRamp.map((step) => step.perDay).join(", ");
+        assumptions.push(`A newly connected mailbox ramps up (${ramp} a day) before it sends at its full daily limit; first_month_capacity shows that month.`);
+    }
+    const planText = recommended
+        ? `cheapest all in: the ${recommended.expected.label} plan${recommended.expected.topup_credits > 0 ? " with top-ups" : ""}${usdSeats > 0 ? " and seats" : ""}, ${formatUsd(recommended.expected.monthly_usd ?? 0)} a month`
+        : "no plan could be priced";
+    const steps = scenario.emailSteps + scenario.linkedinSteps;
+    const scenarioText = `Priced: ${formatInt(leads)} leads a month, ${steps} sequence ${steps === 1 ? "step" : "steps"} per lead (${scenario.emailSteps} email, ${scenario.linkedinSteps} LinkedIn), ${formatInt(totalMailboxes)} ${totalMailboxes === 1 ? "mailbox" : "mailboxes"}, ${formatInt(scenario.linkedinAccounts)} LinkedIn ${scenario.linkedinAccounts === 1 ? "account" : "accounts"}.`;
+    const summary = [
+        scenarioText,
+        `About ${formatInt(credits)} credits a month expected (up to ${formatInt(worstCredits)} worst case)${usdSeats > 0 ? ` plus ${formatUsd(usdSeats)} a month in sending seats` : ""}; ${planText}.`,
+        limitsHit.length > 0
+            ? `Limits hit: ${limits.filter((row) => row.hit).map((row) => `${row.label.toLowerCase()} (needs ${formatInt(row.senders_needed)})`).join(", ")}.`
+            : limits.length > 0 ? "No sending limit is hit." : "",
+    ].filter(Boolean).join(" ");
+    return {
+        lines,
+        totals: {
+            fixed_credits_per_month: fixed,
+            flexible_credits_per_month: flexible,
+            flexible_worst_case_credits_per_month: flexibleWorst,
+            credits_per_month: credits,
+            worst_case_credits_per_month: worstCredits,
+            usd_seats_per_month: usdSeats,
+            unpriced_lines: unpriced,
+        },
+        plan_fit: planFit,
+        recommended_plan: recommended,
+        limits,
+        limits_hit: limitsHit,
+        assumptions,
+        warnings,
+        summary,
+    };
+}

package/node_modules/@oxygen/shared/dist/credit-gate.d.ts

@@ -0,0 +1,26 @@
+import type { PlanGatedCapability } from "./plan-capabilities.js";
+/** PROPOSED name: the specification calls it "the credit-gate flag" without naming it. */
+export declare const CREDIT_GATE_ENABLED_ENV_VAR = "OXYGEN_CREDIT_GATE_ENABLED";
+/**
+ * The commitment kinds that must bill before credits may gate a connect: every
+ * account a customer can connect for itself. Managed mailboxes and warm-up are
+ * bought, not connected, and are out of the gate.
+ */
+export declare const CREDIT_GATE_BILLING_KINDS: readonly ["sending_mailbox", "linkedin_account", "whatsapp_account", "x_account", "phone_number"];
+export type CreditGateKind = (typeof CREDIT_GATE_BILLING_KINDS)[number];
+/**
+ * The plan walls credits replace once the gate is in force (S22). The
+ * reasoning, and the two capabilities that stay walled, live with the wall
+ * itself in `plan-capabilities.ts`; the list sits in this leaf so a client
+ * bundle can ask the question without loading the plan catalog.
+ */
+export declare const CREDIT_GATE_RETIRED_CAPABILITIES: readonly ["sender_connect", "sequence_dispatch", "publishing_deliver", "managed_email_infrastructure"];
+export declare function isCapabilityRetiredByCreditGate(capability: PlanGatedCapability): boolean;
+/**
+ * Whether an operator asked for the credit gate. Off unless set to 1/true/yes/on.
+ * This is the REQUEST only; the gate is in force only when commitments bill every
+ * kind above as well, which `isCreditGateEnabled` checks.
+ */
+export declare function isCreditGateRequested(env?: {
+    [key: string]: string | undefined;
+}): boolean;

package/node_modules/@oxygen/shared/dist/credit-gate.js

@@ -0,0 +1,65 @@
+// The credit-gate flag of the 2026-09 repricing (decision 2.7, spec slices S21
+// and S22): the switch that makes CREDITS, not dollar sending seats, decide
+// whether a workspace may connect an account.
+//
+// WHAT IT MOVES. With the flag off, nothing changes: a connect is judged by the
+// sending-seat gate (`OXYGEN_SENDING_SEAT_GATE_ENABLED`) exactly as today. With it
+// on, a connect is admitted when the spendable balance covers the account's
+// first monthly credit reservation, refused with `insufficient_credits` when it
+// does not, and `billing seats` reports that seats are retired (S21). The plan
+// wall removal (S22) sits behind the same flag.
+//
+// WHY IT IS ITS OWN FLAG, AND WHY IT IS NOT ENOUGH ALONE. A balance check debits
+// nothing: while commitments are dark, a workspace holding 3,400 credits would
+// pass it, connect a LinkedIn account and send for free for good. So the flag
+// only takes effect when every kind below is also being BILLED as a credit
+// commitment and has a price in force, which for X accounts and phone numbers
+// means once the repricing's effective date has passed (`isCreditGateEnabled` in
+// `@oxygen/integrations`), and a process that sees the flag set without the
+// commitments refuses to start (`assertCreditGateArmed`).
+//
+// This leaf holds only the flag's name, its raw reading and the kinds it
+// requires, so request paths can skip the integrations barrel when it is off.
+// Setting it is a production configuration change that needs explicit human
+// approval (spec S95), and it is turned on only after S26 arms every kind.
+/** PROPOSED name: the specification calls it "the credit-gate flag" without naming it. */
+export const CREDIT_GATE_ENABLED_ENV_VAR = "OXYGEN_CREDIT_GATE_ENABLED";
+/**
+ * The commitment kinds that must bill before credits may gate a connect: every
+ * account a customer can connect for itself. Managed mailboxes and warm-up are
+ * bought, not connected, and are out of the gate.
+ */
+export const CREDIT_GATE_BILLING_KINDS = [
+    "sending_mailbox",
+    "linkedin_account",
+    "whatsapp_account",
+    "x_account",
+    "phone_number",
+];
+/**
+ * The plan walls credits replace once the gate is in force (S22). The
+ * reasoning, and the two capabilities that stay walled, live with the wall
+ * itself in `plan-capabilities.ts`; the list sits in this leaf so a client
+ * bundle can ask the question without loading the plan catalog.
+ */
+export const CREDIT_GATE_RETIRED_CAPABILITIES = [
+    "sender_connect",
+    "sequence_dispatch",
+    "publishing_deliver",
+    "managed_email_infrastructure",
+];
+export function isCapabilityRetiredByCreditGate(capability) {
+    return CREDIT_GATE_RETIRED_CAPABILITIES.includes(capability);
+}
+/**
+ * Whether an operator asked for the credit gate. Off unless set to 1/true/yes/on.
+ * This is the REQUEST only; the gate is in force only when commitments bill every
+ * kind above as well, which `isCreditGateEnabled` checks.
+ */
+export function isCreditGateRequested(env = process.env) {
+    const raw = env[CREDIT_GATE_ENABLED_ENV_VAR];
+    if (!raw)
+        return false;
+    const normalized = raw.trim().toLowerCase();
+    return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}

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

@@ -0,0 +1,51 @@
+import type { SequenceSendWindow } from "./sequences.js";
+/** Deliverability defaults are independent of pricing and confer no send/spend authority. */
+export declare const EMAIL_DELIVERABILITY_POLICY_VERSION = "2026-09-27-v1";
+export declare const EMAIL_DELIVERABILITY_DEFAULTS: Readonly<{
+    campaignDailyCap: 25;
+    campaignGapMinutes: 12;
+    trackingOpens: false;
+    trackingClicks: false;
+    warmupInitialPerDay: 1;
+    warmupIncreasePerDay: 1;
+    warmupMaxPerDay: 10;
+    combinedVolumeWarning: 50;
+    bounceWarningRate: 0.02;
+    bouncePauseRate: 0.03;
+    bounceMinSends: 20;
+    bounceWindowDays: 7;
+}>;
+export type EmailBounceProtection = {
+    enabled: boolean;
+    warning_rate: number;
+    pause_rate: number;
+    min_sends: number;
+    window_days: number;
+};
+export declare function resolveEmailBounceProtection(value?: unknown): EmailBounceProtection;
+export declare function defaultEmailSendWindow(timezone?: string | null): SequenceSendWindow;
+/** Completed UTC days with an accepted campaign send; import age is not evidence. */
+export declare function campaignSendingDays(metadata: unknown, now?: Date): number;
+/** Fill absent settings only. Explicit zero caps/gaps and schedules remain choices. */
+export declare function resolveEmailDeliverabilityPolicy(input?: {
+    settings?: {
+        max_emails_per_mailbox_per_day?: number;
+        email_min_gap_minutes?: number;
+        email_send_window?: SequenceSendWindow;
+    } | null;
+    trackingOpens?: boolean | null;
+    trackingClicks?: boolean | null;
+    workspaceTimezone?: string | null;
+}): {
+    version: string;
+    campaignDailyCap: number;
+    campaignGapMinutes: number;
+    sendWindow: SequenceSendWindow;
+    trackingOpens: boolean;
+    trackingClicks: boolean;
+    externalSendingMeasured: boolean;
+};
+/** Strict authoring validation; the resolver remains defensive for legacy rows. */
+export declare function validateEmailBounceProtection(value: unknown): void;
+/** Inspect executable signal/metric fields, never authored prose. */
+export declare function missingEmailTracking(definition: unknown, opens: boolean, clicks: boolean, autoOptimize?: boolean): string[];

package/node_modules/@oxygen/shared/dist/email-deliverability-policy.js

@@ -0,0 +1,101 @@
+/** Deliverability defaults are independent of pricing and confer no send/spend authority. */
+export const EMAIL_DELIVERABILITY_POLICY_VERSION = "2026-09-27-v1";
+export const EMAIL_DELIVERABILITY_DEFAULTS = Object.freeze({
+    campaignDailyCap: 25,
+    campaignGapMinutes: 12,
+    trackingOpens: false,
+    trackingClicks: false,
+    warmupInitialPerDay: 1,
+    warmupIncreasePerDay: 1,
+    warmupMaxPerDay: 10,
+    combinedVolumeWarning: 50,
+    bounceWarningRate: 0.02,
+    bouncePauseRate: 0.03,
+    bounceMinSends: 20,
+    bounceWindowDays: 7,
+});
+export function resolveEmailBounceProtection(value) {
+    const record = value && typeof value === "object" ? value : {};
+    const number = (key, fallback, min, max, integer = false) => {
+        const v = record[key];
+        return typeof v === "number" && Number.isFinite(v) && v >= min && v <= max
+            && (!integer || Number.isInteger(v)) ? v : fallback;
+    };
+    return {
+        enabled: record.enabled !== false,
+        warning_rate: number("warning_rate", EMAIL_DELIVERABILITY_DEFAULTS.bounceWarningRate, 0, 1),
+        pause_rate: number("pause_rate", EMAIL_DELIVERABILITY_DEFAULTS.bouncePauseRate, 0, 1),
+        min_sends: number("min_sends", EMAIL_DELIVERABILITY_DEFAULTS.bounceMinSends, 1, 100000, true),
+        window_days: number("window_days", EMAIL_DELIVERABILITY_DEFAULTS.bounceWindowDays, 1, 90, true),
+    };
+}
+export function defaultEmailSendWindow(timezone) {
+    let zone = timezone?.trim() || "UTC";
+    try {
+        new Intl.DateTimeFormat("en", { timeZone: zone }).format();
+    }
+    catch {
+        zone = "UTC";
+    }
+    return { timezone: zone, days: [1, 2, 3, 4, 5], start: "09:00", end: "17:00" };
+}
+/** Completed UTC days with an accepted campaign send; import age is not evidence. */
+export function campaignSendingDays(metadata, now = new Date()) {
+    const record = metadata && typeof metadata === "object" ? metadata : {};
+    const days = record.campaign_sending_days;
+    if (!Array.isArray(days))
+        return 0;
+    const today = now.toISOString().slice(0, 10);
+    return new Set(days.filter((day) => typeof day === "string"
+        && /^\d{4}-\d{2}-\d{2}$/.test(day) && day < today)).size;
+}
+/** Fill absent settings only. Explicit zero caps/gaps and schedules remain choices. */
+export function resolveEmailDeliverabilityPolicy(input = {}) {
+    return {
+        version: EMAIL_DELIVERABILITY_POLICY_VERSION,
+        campaignDailyCap: input.settings?.max_emails_per_mailbox_per_day ?? EMAIL_DELIVERABILITY_DEFAULTS.campaignDailyCap,
+        campaignGapMinutes: input.settings?.email_min_gap_minutes ?? EMAIL_DELIVERABILITY_DEFAULTS.campaignGapMinutes,
+        sendWindow: input.settings?.email_send_window ?? defaultEmailSendWindow(input.workspaceTimezone),
+        trackingOpens: input.trackingOpens ?? EMAIL_DELIVERABILITY_DEFAULTS.trackingOpens,
+        trackingClicks: input.trackingClicks ?? EMAIL_DELIVERABILITY_DEFAULTS.trackingClicks,
+        externalSendingMeasured: false,
+    };
+}
+/** Strict authoring validation; the resolver remains defensive for legacy rows. */
+export function validateEmailBounceProtection(value) {
+    if (value === undefined)
+        return;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("bounce_protection must be an object.");
+    const record = value;
+    const resolved = resolveEmailBounceProtection(record);
+    for (const [key, configured] of Object.entries(record)) {
+        if (!(key in resolved) || resolved[key] !== configured) {
+            throw new Error(`Invalid bounce_protection.${key}. Use enabled (boolean), rates from 0 to 1, min_sends from 1 to 100000, and window_days from 1 to 90.`);
+        }
+    }
+}
+/** Inspect executable signal/metric fields, never authored prose. */
+export function missingEmailTracking(definition, opens, clicks, autoOptimize = true) {
+    const missing = new Set();
+    const visit = (value) => {
+        if (!value || typeof value !== "object")
+            return;
+        if (Array.isArray(value)) {
+            value.forEach(visit);
+            return;
+        }
+        for (const [key, child] of Object.entries(value)) {
+            if (key === "auto_optimize" && !autoOptimize)
+                continue;
+            if ((key === "signal" && child === "email_opened" || key === "metric" && child === "open") && !opens)
+                missing.add("opens");
+            if ((key === "signal" && child === "email_clicked" || key === "metric" && child === "click") && !clicks)
+                missing.add("clicks");
+            if (typeof child === "object")
+                visit(child);
+        }
+    };
+    visit(definition);
+    return [...missing];
+}

package/node_modules/@oxygen/shared/dist/email-hard-bounce.d.ts

@@ -0,0 +1,27 @@
+/**
+ * PURE hard-bounce rule: when a fleet's bounces are a reputation problem rather
+ * than list noise.
+ *
+ * WHY it lives in @oxygen/shared and not next to the other email-health rules in
+ * @oxygen/integrations: the tenant rollup applies it per mailbox, and
+ * @oxygen/tenant-db must never import @oxygen/integrations (integrations depends
+ * on tenant-db). It is re-exported from
+ * packages/integrations/src/email-health/health-state.ts, which stays the
+ * email-health surface every caller reads.
+ *
+ * DIRECTIONAL: it produces a warning, never pauses a mailbox or changes a cap.
+ */
+/** Hard-bounce rate above which a fleet is burning its domains, not just its list. */
+export declare const HARD_BOUNCE_RATE_CEILING = 0.02;
+/** Below this send volume a bounce rate is noise, not a signal. */
+export declare const HARD_BOUNCE_RATE_MIN_SENDS = 20;
+/**
+ * True when a hard-bounce count is high enough, over enough sends, to be a real
+ * reputation problem rather than list noise.
+ */
+export declare function hardBounceRateIsHigh(input: {
+    hardBounces: number;
+    coldSends: number;
+    warningRate?: number;
+    minSends?: number;
+}): boolean;

package/node_modules/@oxygen/shared/dist/email-hard-bounce.js

@@ -0,0 +1,27 @@
+/**
+ * PURE hard-bounce rule: when a fleet's bounces are a reputation problem rather
+ * than list noise.
+ *
+ * WHY it lives in @oxygen/shared and not next to the other email-health rules in
+ * @oxygen/integrations: the tenant rollup applies it per mailbox, and
+ * @oxygen/tenant-db must never import @oxygen/integrations (integrations depends
+ * on tenant-db). It is re-exported from
+ * packages/integrations/src/email-health/health-state.ts, which stays the
+ * email-health surface every caller reads.
+ *
+ * DIRECTIONAL: it produces a warning, never pauses a mailbox or changes a cap.
+ */
+/** Hard-bounce rate above which a fleet is burning its domains, not just its list. */
+export const HARD_BOUNCE_RATE_CEILING = 0.02;
+/** Below this send volume a bounce rate is noise, not a signal. */
+export const HARD_BOUNCE_RATE_MIN_SENDS = 20;
+/**
+ * True when a hard-bounce count is high enough, over enough sends, to be a real
+ * reputation problem rather than list noise.
+ */
+export function hardBounceRateIsHigh(input) {
+    if (!Number.isFinite(input.coldSends) || input.coldSends < (input.minSends ?? HARD_BOUNCE_RATE_MIN_SENDS)) {
+        return false;
+    }
+    return input.hardBounces / input.coldSends > (input.warningRate ?? HARD_BOUNCE_RATE_CEILING);
+}