@oxygen-agent/cli 1.1014.620 → 1.1014.773

package/node_modules/@oxygen/shared/dist/sequences.js

@@ -156,582 +156,8 @@ export function recipientEmailFromRow(rowValues, emailColumnKey) {
     }
     return null;
 }
-/**
- * ESP (email service provider) MATCHING mode for a sequence (settings.esp_matching).
- * Deliverability lore: a send lands better when the SENDING mailbox and the
- * RECIPIENT sit on the same provider (Google→Google, Microsoft→Microsoft), so at
- * mailbox-pick the dispatcher can bias rotation toward a same-ESP mailbox.
- *   - "off"    — no ESP bias; rotation is pure LRU / domain-spread.
- *   - "prefer" — (DEFAULT) pick a same-ESP mailbox when one is available, else
- *     fall back to any sendable mailbox (never blocks a send). On by default
- *     because it only ever improves deliverability and cannot starve sends.
- *   - "strict" — require a same-ESP mailbox; when none is available the action is
- *     DEFERRED with a visible skipped_reason rather than sent cross-provider.
- *     Power-user setting, reachable via CLI/MCP; the web "Provider Matching"
- *     checkbox toggles off↔prefer only.
- */
-export const ESP_MATCHING_MODES = ["off", "prefer", "strict"];
-// Provider Matching is ON by default (prefer): a same-provider send lands better,
-// and prefer never blocks — an absent setting biases mailbox pick without risk.
-export const DEFAULT_ESP_MATCHING_MODE = "prefer";
-export function isEspMatchingMode(value) {
-    return typeof value === "string" && ESP_MATCHING_MODES.includes(value);
-}
-/**
- * Validate settings.esp_matching before persistence. Absent/null is valid and
- * means DEFAULT_ESP_MATCHING_MODE, which is "prefer" — an unset sequence still
- * biases rotation toward a same-provider sender, so a workspace whose senders on
- * one provider are in bad standing concentrates that provider's recipients on
- * them until an operator sets "off". Any other value must be one of the three
- * modes. Pure; throws OxygenError("invalid_sequence_settings") on a bad value so
- * the CLI / MCP / API report an identical error. Called from the tenant-db
- * settings validator alongside the budget/prioritization checks.
- */
-export function validateEspMatchingSetting(value) {
-    if (value === undefined || value === null)
-        return;
-    if (typeof value === "string" || typeof value !== "object" || Array.isArray(value)) {
-        if (!isEspMatchingMode(value)) {
-            throw new OxygenError("invalid_sequence_settings", `settings.esp_matching must be one of: ${ESP_MATCHING_MODES.join(", ")}.`, { details: { field: "esp_matching", value }, exitCode: 1 });
-        }
-        return;
-    }
-    validateEspRoutingPolicy(value);
-}
-/** Throw with the exact jsonb path that failed, so a typo is nameable rather than mysterious. */
-function espSettingError(path, message, value) {
-    return new OxygenError("invalid_sequence_settings", `settings.${path} ${message}`, {
-        details: { field: "esp_matching", path: `esp_matching.${path.replace(/^esp_matching\.?/, "")}`, ...(value === undefined ? {} : { value }) },
-        exitCode: 1,
-    });
-}
-/**
- * Strict validation of the object form, the write-path counterpart to the
- * lenient espPolicyFromSetting. Deliberately rejects UNKNOWN TOP-LEVEL KEYS by
- * name: this setting's failure mode is invisible — a policy that silently did
- * nothing because someone wrote "routs" would be discovered only as a month of
- * mail sent from the wrong fleet.
- */
-function validateEspRoutingPolicy(record) {
-    const allowed = new Set(["mode", "routes", "exclude"]);
-    for (const key of Object.keys(record)) {
-        if (!allowed.has(key)) {
-            throw espSettingError("esp_matching", `has an unknown key "${key}"; expected mode, routes or exclude.`);
-        }
-    }
-    if (record.mode !== undefined && record.mode !== null && !isEspMatchingMode(record.mode)) {
-        throw espSettingError("esp_matching.mode", `must be one of: ${ESP_MATCHING_MODES.join(", ")}.`, record.mode);
-    }
-    if (record.routes !== undefined && record.routes !== null) {
-        if (typeof record.routes !== "object" || Array.isArray(record.routes)) {
-            throw espSettingError("esp_matching.routes", "must be an object keyed by recipient provider.");
-        }
-        for (const [bucket, weights] of Object.entries(record.routes)) {
-            if (!isEspRouteBucket(bucket)) {
-                throw espSettingError("esp_matching.routes", `has an unknown recipient "${bucket}"; expected one of: ${ESP_ROUTE_BUCKETS.join(", ")}.`);
-            }
-            if (typeof weights !== "object" || weights === null || Array.isArray(weights)) {
-                throw espSettingError(`esp_matching.routes.${bucket}`, "must be an object of sender weights.");
-            }
-            for (const [provider, weight] of Object.entries(weights)) {
-                if (!RECIPIENT_ESPS.includes(provider)) {
-                    throw espSettingError(`esp_matching.routes.${bucket}`, `has an unknown sender "${provider}"; expected one of: ${RECIPIENT_ESPS.join(", ")}.`);
-                }
-                if (typeof weight !== "number" || !Number.isFinite(weight) || weight < 0 || weight > MAX_ESP_ROUTE_WEIGHT) {
-                    throw espSettingError(`esp_matching.routes.${bucket}.${provider}`, `must be a number between 0 and ${MAX_ESP_ROUTE_WEIGHT}.`, weight);
-                }
-            }
-        }
-    }
-    if (record.exclude !== undefined && record.exclude !== null) {
-        if (!Array.isArray(record.exclude)) {
-            throw espSettingError("esp_matching.exclude", "must be an array of sender-domain exclusions.");
-        }
-        if (record.exclude.length > MAX_ESP_SENDER_EXCLUSIONS) {
-            throw espSettingError("esp_matching.exclude", `must hold at most ${MAX_ESP_SENDER_EXCLUSIONS} entries; it is a routing policy, not a suppression list.`);
-        }
-        record.exclude.forEach((entry, index) => {
-            if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
-                throw espSettingError(`esp_matching.exclude[${index}]`, "must be an object with a domain.");
-            }
-            const item = entry;
-            for (const key of Object.keys(item)) {
-                if (key !== "domain" && key !== "from_recipients") {
-                    throw espSettingError(`esp_matching.exclude[${index}]`, `has an unknown key "${key}".`);
-                }
-            }
-            if (typeof item.domain !== "string" || !normalizeEspSenderDomain(item.domain)) {
-                throw espSettingError(`esp_matching.exclude[${index}].domain`, "must be a non-empty sending domain.", item.domain);
-            }
-            if (normalizeEspSenderDomain(item.domain).length > 253) {
-                throw espSettingError(`esp_matching.exclude[${index}].domain`, "must be at most 253 characters.");
-            }
-            if (item.from_recipients !== undefined && item.from_recipients !== null) {
-                if (!Array.isArray(item.from_recipients) || !item.from_recipients.every(isEspRouteBucket)) {
-                    throw espSettingError(`esp_matching.exclude[${index}].from_recipients`, `must be an array of: ${ESP_ROUTE_BUCKETS.join(", ")}.`);
-                }
-            }
-        });
-    }
-}
-/**
- * The MATCHABLE email-provider a recipient routes through — the narrow set ESP
- * matching can act on. Kept intentionally aligned with EMAIL_MAILBOX_PROVIDERS in
- * tenant-db so a mailbox's `provider` and a resolved recipient ESP compare
- * directly: we can only bias rotation toward a provider we can actually SEND
- * from, and the pool is Google/Microsoft only.
- *
- * This is deliberately NARROWER than RECIPIENT_ESP_FAMILIES (what we DISPLAY).
- * A domain behind Proofpoint has family "proofpoint" but may still be matchable
- * as "microsoft" — see resolveEspFamily.
- */
-export const RECIPIENT_ESPS = ["google", "microsoft"];
-/**
- * WEIGHTED SENDER ROUTING — the object form of settings.esp_matching.
- *
- * The three scalar modes above answer one question ("bias toward the recipient's
- * own provider, yes or no"), and they bake in the assumption that same-provider
- * is always better. That assumption fails whenever one provider's senders are in
- * bad standing: a workspace whose Google-hosted domains are refused by Gmail
- * wants its Google-hosted RECIPIENTS served from Microsoft senders, which no
- * scalar mode can express. "off" does not express it either, because free
- * rotation still hands Google recipients a Google sender in proportion to the
- * pool.
- *
- * So the object form states the routing directly, as SEND SHARES per recipient
- * provider:
- *
- *   { mode: "prefer",
- *     routes: { google: { microsoft: 100 }, microsoft: { microsoft: 100 } },
- *     exclude: [{ domain: "burned.example", from_recipients: ["google"] }] }
- *
- * `routes` is keyed by the RECIPIENT's resolved provider; the inner map is the
- * SENDER provider. Weights are relative shares, so { google: 3, microsoft: 1 }
- * and { google: 75, microsoft: 25 } are the same policy and nothing has to sum
- * to 100. An omitted weight is zero. A bucket whose entry is explicitly present
- * but carries no positive weight means "no opinion, rotate freely for this
- * recipient class"; a bucket the operator never mentioned keeps the historical
- * same-provider default, so editing Google routing cannot silently change how
- * Microsoft recipients are served.
- *
- * `exclude` is a hard never, not a preference: a sender domain listed here is
- * removed from the candidate pool for the named recipient buckets (all buckets
- * when `from_recipients` is absent) in EVERY mode, including "off", and it
- * survives the prefer-fallback. A deliverability guard that a matching toggle
- * could disarm would not be a guard.
- *
- * The scalar modes remain valid values and are read as policies, so there is one
- * routing code path rather than two: "prefer" becomes { mode: "prefer" } with no
- * routes, which resolves to the same-provider default and behaves exactly as it
- * did before.
- */
-export const ESP_ROUTE_BUCKETS = ["google", "microsoft", "unknown"];
-/** Cap on settings.esp_matching.exclude — a routing policy, not a suppression list. */
-export const MAX_ESP_SENDER_EXCLUSIONS = 50;
-/** Upper bound on a single route weight; relative shares never need more. */
-export const MAX_ESP_ROUTE_WEIGHT = 1_000_000;
-export function isEspRouteBucket(value) {
-    return typeof value === "string" && ESP_ROUTE_BUCKETS.includes(value);
-}
-function isRecipientEspValue(value) {
-    return typeof value === "string" && RECIPIENT_ESPS.includes(value);
-}
-/**
- * A sending domain as the mailbox table stores it: lowercase, no leading "@".
- * Mirrors lower(split_part(email_address, '@', 2)) in pickEmailMailbox so an
- * exclusion the operator typed as "@Burned.Example " still matches.
- */
-export function normalizeEspSenderDomain(value) {
-    return value.trim().toLowerCase().replace(/^@+/, "");
-}
-/**
- * LENIENT read of a persisted settings.esp_matching (never throws — a read must
- * not break a send). Absent, null, or malformed reads as the default policy, and
- * a malformed FIELD bails the WHOLE object rather than half-applying a routing
- * policy, which is the readMailboxRampConfig convention in tenant-db. The strict
- * counterpart that guards the write path is validateEspMatchingSetting.
- */
-export function espPolicyFromSetting(value) {
-    const fallback = { mode: DEFAULT_ESP_MATCHING_MODE, routes: {}, exclude: [] };
-    if (value === undefined || value === null)
-        return fallback;
-    if (typeof value === "string") {
-        return isEspMatchingMode(value) ? { mode: value, routes: {}, exclude: [] } : fallback;
-    }
-    if (typeof value !== "object" || Array.isArray(value))
-        return fallback;
-    const record = value;
-    const mode = record.mode === undefined || record.mode === null ? DEFAULT_ESP_MATCHING_MODE : record.mode;
-    if (!isEspMatchingMode(mode))
-        return fallback;
-    const routes = {};
-    if (record.routes !== undefined && record.routes !== null) {
-        if (typeof record.routes !== "object" || Array.isArray(record.routes))
-            return fallback;
-        for (const [bucket, raw] of Object.entries(record.routes)) {
-            if (!isEspRouteBucket(bucket))
-                return fallback;
-            if (typeof raw !== "object" || raw === null || Array.isArray(raw))
-                return fallback;
-            const weights = {};
-            for (const [provider, weight] of Object.entries(raw)) {
-                if (!isRecipientEspValue(provider))
-                    return fallback;
-                if (typeof weight !== "number" || !Number.isFinite(weight) || weight < 0)
-                    return fallback;
-                weights[provider] = weight;
-            }
-            routes[bucket] = weights;
-        }
-    }
-    const exclude = [];
-    if (record.exclude !== undefined && record.exclude !== null) {
-        if (!Array.isArray(record.exclude))
-            return fallback;
-        for (const entry of record.exclude) {
-            if (typeof entry !== "object" || entry === null || Array.isArray(entry))
-                return fallback;
-            const item = entry;
-            if (typeof item.domain !== "string")
-                return fallback;
-            const domain = normalizeEspSenderDomain(item.domain);
-            if (!domain)
-                return fallback;
-            let buckets = ESP_ROUTE_BUCKETS;
-            if (item.from_recipients !== undefined && item.from_recipients !== null) {
-                if (!Array.isArray(item.from_recipients))
-                    return fallback;
-                if (item.from_recipients.length > 0) {
-                    if (!item.from_recipients.every(isEspRouteBucket))
-                        return fallback;
-                    buckets = item.from_recipients;
-                }
-            }
-            exclude.push({ domain, buckets });
-        }
-    }
-    return { mode, routes, exclude };
-}
-/**
- * The effective send shares for one recipient bucket. An explicitly-present
- * entry wins even when it is empty or all-zero (that is the operator saying
- * "rotate freely here"); a bucket that was never mentioned keeps the historical
- * same-provider default, and "unknown" has no same-provider to default to.
- */
-export function espRouteWeightsFor(policy, bucket) {
-    const configured = policy.routes[bucket];
-    if (configured)
-        return configured;
-    return bucket === "unknown" ? {} : { [bucket]: 1 };
-}
-/**
- * The sender providers to try, best first, for one recipient bucket — a
- * deterministic weighted shuffle WITHOUT replacement.
- *
- * Returning an ORDER rather than a single draw is what makes "prefer" correct:
- * a 90/10 Google policy over a pool holding no Google mailbox must send 100%
- * from Microsoft, not defer and not fall through to provider-blind rotation.
- * An empty result means "no opinion" and the caller rotates freely.
- *
- * Deterministic by construction: the seed carries the enrollment and step, never
- * a clock or Math.random, so a dry-run preview and the later live send choose
- * the same provider, and a replan after a defer re-derives the same route.
- * Candidates are enumerated in RECIPIENT_ESPS order rather than object-key
- * order, because jsonb does not preserve key order and a policy that round-trips
- * through the database must not reroute the fleet.
- */
-export function espRouteCandidates(input) {
-    const weights = espRouteWeightsFor(input.policy, input.recipient);
-    let pool = RECIPIENT_ESPS.map((provider) => ({ provider, weight: weights[provider] ?? 0 })).filter((entry) => Number.isFinite(entry.weight) && entry.weight > 0);
-    const order = [];
-    let draw = 0;
-    while (pool.length > 0) {
-        const total = pool.reduce((sum, entry) => sum + entry.weight, 0);
-        // Re-hash per draw rather than reusing the residue: a second draw derived
-        // from the first would correlate the tail of the order with its head.
-        const seed = draw === 0 ? input.seed : `${input.seed}:${draw + 1}`;
-        const target = ((hashVariantKey(seed) % 1_000_000) / 1_000_000) * total;
-        let cumulative = 0;
-        let chosen = pool[pool.length - 1].provider;
-        for (const entry of pool) {
-            cumulative += entry.weight;
-            if (target < cumulative) {
-                chosen = entry.provider;
-                break;
-            }
-        }
-        order.push(chosen);
-        pool = pool.filter((entry) => entry.provider !== chosen);
-        draw += 1;
-    }
-    return order;
-}
-/**
- * Sending domains that must not serve this recipient bucket, normalized and
- * de-duplicated for pickEmailMailbox. Applies in every mode and survives the
- * prefer-fallback — see the exclude contract above.
- */
-export function espExcludedSenderDomains(policy, bucket) {
-    const domains = new Set();
-    for (const entry of policy.exclude) {
-        if (entry.buckets.includes(bucket))
-            domains.add(entry.domain);
-    }
-    return [...domains];
-}
-/**
- * The DISPLAY taxonomy: the mail-infrastructure family a recipient domain sits
- * on. Wider than RecipientEsp because "everything that isn't Google or Microsoft"
- * is not one thing — a list that is 23% Proofpoint is a very different
- * deliverability problem from one that is 23% self-hosted, and collapsing both to
- * null (today's behavior) hides that. Split into three groups:
- *
- *   - MAILBOX providers (google, microsoft) — imply a matchable ESP.
- *   - GATEWAY vendors (proofpoint, mimecast, ...) — security filters that sit IN
- *     FRONT of a mailbox provider. Their MX tells you the filter, NOT where the
- *     mailbox lives; the SPF fallback is what sees behind them.
- *   - OTHER mailbox hosts (zoho, yahoo, fastmail, ...) and self_hosted — real
- *     destinations we simply cannot send as, so never matchable.
- */
-export const RECIPIENT_ESP_FAMILIES = [
-    "google",
-    "microsoft",
-    "proofpoint",
-    "mimecast",
-    "barracuda",
-    "cisco",
-    "zscaler",
-    "trendmicro",
-    "sophos",
-    "zoho",
-    "yahoo",
-    "apple",
-    "proton",
-    "fastmail",
-    "gmx",
-    "amazon",
-    "self_hosted",
-];
-export function isRecipientEspFamily(value) {
-    return typeof value === "string" && RECIPIENT_ESP_FAMILIES.includes(value);
-}
-/**
- * Families that are inbound SECURITY GATEWAYS rather than mailbox hosts. Seeing
- * one in MX means the real mailbox provider is hidden behind it, so the resolver
- * must fall through to the SPF signal instead of concluding "not Google/Microsoft".
- * This is the single most important distinction in this file: treating a
- * Proofpoint MX as "no known ESP" is how a Microsoft-hosted list silently loses
- * ESP matching.
- */
-const GATEWAY_FAMILIES = new Set([
-    "proofpoint",
-    "mimecast",
-    "barracuda",
-    "cisco",
-    "zscaler",
-    "trendmicro",
-    "sophos",
-]);
-export function isEspGatewayFamily(family) {
-    return family !== null && family !== undefined && GATEWAY_FAMILIES.has(family);
-}
-/**
- * The matchable ESP a display family implies, or null when the family is a
- * gateway (unknown until SPF) or a provider we cannot send as. The ONLY place
- * family → esp is decided, so display and matching can't drift.
- */
-export function matchableEspFromFamily(family) {
-    if (family === "google" || family === "microsoft")
-        return family;
-    return null;
-}
-/**
- * Consumer/freemail domains that resolve deterministically from the domain string
- * with NO network call. Only google/microsoft are matchable; the rest are display
- * families (a list heavy on these is a list-quality signal worth surfacing).
- */
-const CONSUMER_DOMAIN_FAMILIES = new Map([
-    ["gmail.com", "google"],
-    ["googlemail.com", "google"],
-    ["outlook.com", "microsoft"],
-    ["hotmail.com", "microsoft"],
-    ["live.com", "microsoft"],
-    ["msn.com", "microsoft"],
-    ["yahoo.com", "yahoo"],
-    ["yahoo.co.uk", "yahoo"],
-    ["ymail.com", "yahoo"],
-    ["aol.com", "yahoo"],
-    ["icloud.com", "apple"],
-    ["me.com", "apple"],
-    ["mac.com", "apple"],
-    ["proton.me", "proton"],
-    ["protonmail.com", "proton"],
-    ["pm.me", "proton"],
-    ["fastmail.com", "fastmail"],
-    ["zoho.com", "zoho"],
-    ["gmx.com", "gmx"],
-    ["gmx.de", "gmx"],
-    ["web.de", "gmx"],
-]);
-/**
- * Normalize a recipient domain: lowercase, trim, drop a trailing FQDN dot, and if
- * a full address is passed take the part after the last '@'. Returns "" for junk.
- */
-function normalizeRecipientDomain(domain) {
-    if (typeof domain !== "string")
-        return "";
-    let d = domain.trim().toLowerCase();
-    const at = d.lastIndexOf("@");
-    if (at >= 0)
-        d = d.slice(at + 1);
-    return d.replace(/\.+$/, "");
-}
-/**
- * Does `host` sit at or under `suffix`? Requires a DOT boundary, so "google.com"
- * matches "aspmx.l.google.com" and itself but NOT "notgoogle.com" — a bare
- * endsWith() would map an unrelated lookalike domain onto a real ESP family and,
- * under strict matching, route a send at the wrong pool.
- */
-function hostMatchesSuffix(host, suffix) {
-    return host === suffix || host.endsWith(`.${suffix}`);
-}
-/**
- * MX exchange-host suffix → display family, most specific first. Every entry is
- * the vendor's own mail-routing domain (what shows up in a real MX answer):
- * Google Workspace publishes aspmx.l.google.com, Microsoft 365 publishes
- * <tenant>.mail.protection.outlook.com, Proofpoint pphosted.com, and so on.
- */
-const MX_FAMILY_SUFFIXES = [
-    ["protection.outlook.com", "microsoft"],
-    ["outlook.com", "microsoft"],
-    ["google.com", "google"],
-    ["googlemail.com", "google"],
-    ["pphosted.com", "proofpoint"],
-    ["ppe-hosted.com", "proofpoint"],
-    ["mimecast.com", "mimecast"],
-    ["mimecast.co.za", "mimecast"],
-    ["mimecast-offshore.com", "mimecast"],
-    ["barracudanetworks.com", "barracuda"],
-    ["barracuda.com", "barracuda"],
-    ["iphmx.com", "cisco"],
-    ["cisco.com", "cisco"],
-    ["zscaler.net", "zscaler"],
-    ["zscalerthree.net", "zscaler"],
-    ["trendmicro.com", "trendmicro"],
-    ["trendmicro.eu", "trendmicro"],
-    ["sophos.com", "sophos"],
-    ["zoho.com", "zoho"],
-    ["zoho.eu", "zoho"],
-    ["yahoodns.net", "yahoo"],
-    ["icloud.com", "apple"],
-    ["protonmail.ch", "proton"],
-    ["proton.me", "proton"],
-    ["messagingengine.com", "fastmail"],
-    ["gmx.net", "gmx"],
-    ["amazonaws.com", "amazon"],
-    ["awsapps.com", "amazon"],
-];
-/**
- * Map a domain's resolved MX exchange hostnames to a DISPLAY family. Returns null
- * when no host matches any known vendor — the caller records that as
- * "self_hosted" only once it is sure the lookup itself succeeded (an empty/failed
- * answer is "unknown", which is a different fact).
- */
-export function familyFromMxHosts(hosts) {
-    if (!Array.isArray(hosts))
-        return null;
-    for (const raw of hosts) {
-        if (typeof raw !== "string")
-            continue;
-        const host = raw.trim().toLowerCase().replace(/\.+$/, "");
-        if (!host)
-            continue;
-        for (const [suffix, family] of MX_FAMILY_SUFFIXES) {
-            if (hostMatchesSuffix(host, suffix))
-                return family;
-        }
-    }
-    return null;
-}
-/**
- * SPF `include:` targets that identify the ESP a domain SENDS through — the
- * signal that sees behind an inbound security gateway. An org filtering inbound
- * mail through Proofpoint still relays its own outbound via Microsoft 365, and
- * says so in SPF, so this recovers a matchable ESP that MX alone cannot.
- */
-const SPF_INCLUDE_ESPS = [
-    ["spf.protection.outlook.com", "microsoft"],
-    ["spf.protection.office365.us", "microsoft"],
-    ["_spf.google.com", "google"],
-    ["_spf.googlemail.com", "google"],
-    ["aspmx.googlemail.com", "google"],
-];
-/**
- * Resolve the matchable ESP from a domain's TXT records by reading its SPF
- * mechanisms. Scans every `v=spf1` record's include:/redirect= targets.
- *
- * AMBIGUITY IS NOT GUESSED: a domain mid-migration (or running Workspace
- * alongside an Office tenant) can include BOTH vendors. Returning either one
- * would be a coin flip that strict matching then acts on, so a both-match
- * degrades to null ("unknown") and the caller falls back / defers honestly.
- */
-export function espFromSpfRecords(records) {
-    if (!Array.isArray(records))
-        return null;
-    const found = new Set();
-    for (const raw of records) {
-        if (typeof raw !== "string")
-            continue;
-        const record = raw.trim().toLowerCase().replace(/^"|"$/g, "");
-        if (!record.startsWith("v=spf1"))
-            continue;
-        for (const term of record.split(/\s+/)) {
-            const target = term.startsWith("include:")
-                ? term.slice("include:".length)
-                : term.startsWith("redirect=")
-                    ? term.slice("redirect=".length)
-                    : null;
-            if (!target)
-                continue;
-            const host = target.replace(/\.+$/, "");
-            for (const [suffix, esp] of SPF_INCLUDE_ESPS) {
-                if (hostMatchesSuffix(host, suffix))
-                    found.add(esp);
-            }
-        }
-    }
-    return found.size === 1 ? [...found][0] : null;
-}
-/**
- * Infer a recipient's DISPLAY family from its domain string alone,
- * DETERMINISTICALLY, for the well-known consumer/freemail domains. Returns null
- * for any other domain — the caller then resolves via the cached MX (+ SPF)
- * lookup, because a custom domain fronted by Workspace / M365 / a gateway is not
- * decidable from the string. Pure: the single source of truth for the map.
- */
-export function inferRecipientEspFamily(domain) {
-    const d = normalizeRecipientDomain(domain);
-    if (!d)
-        return null;
-    return CONSUMER_DOMAIN_FAMILIES.get(d) ?? null;
-}
-/**
- * Infer a recipient's MATCHABLE ESP from its domain string. Narrow by design:
- * only the Google/Microsoft consumer domains resolve here, everything else
- * (including yahoo/proton/icloud, which are real but unsendable-as) is null.
- * Unchanged contract — the dispatcher's fast path still calls this.
- */
-export function inferRecipientEsp(domain) {
-    return matchableEspFromFamily(inferRecipientEspFamily(domain));
-}
-/**
- * Back-compat narrow view of familyFromMxHosts: MX hosts → matchable ESP. Now
- * derived from the family table so the two can't drift, and gateway MX hosts
- * correctly yield null here (they need the SPF signal to become matchable).
- */
-export function espFromMxHosts(hosts) {
-    return matchableEspFromFamily(familyFromMxHosts(hosts));
-}
+// Existing Sequence imports retain the same ESP contract and function identities.
+export { ESP_MATCHING_MODES, DEFAULT_ESP_MATCHING_MODE, isEspMatchingMode, validateEspMatchingSetting, RECIPIENT_ESPS, ESP_ROUTE_BUCKETS, MAX_ESP_SENDER_EXCLUSIONS, MAX_ESP_ROUTE_WEIGHT, isEspRouteBucket, normalizeEspSenderDomain, espPolicyFromSetting, espRouteWeightsFor, espRouteCandidates, espExcludedSenderDomains, RECIPIENT_ESP_FAMILIES, isRecipientEspFamily, isEspGatewayFamily, matchableEspFromFamily, familyFromMxHosts, espFromSpfRecords, inferRecipientEspFamily, inferRecipientEsp, espFromMxHosts, } from "./sequence-internals/esp-policy.js";
 /**
  * row_values keys an enrollment's phone number may live under, in
  * send-precedence order, for WhatsApp sends. The enroll path resolves the FIRST