@catalystiq/envoy-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2072 @@
+import { Resend } from 'resend';
+import Anthropic from '@anthropic-ai/sdk';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
+
+/**
+ * Minimal structural shape of a `pg`-compatible query result. We only depend on `rows`
+ * (and intentionally NOT on `rowCount` — see invariant 1). `T` is the row shape.
+ */
+interface SdkQueryResult<T = Record<string, unknown>> {
+    rows: T[];
+}
+/**
+ * The host-supplied pool. Structurally compatible with node-postgres' `Pool` and Neon's
+ * serverless `Pool` — both expose `query(text, params?) => Promise<{ rows }>`. We keep this
+ * deliberately narrow so the SDK takes no hard dependency on a specific `pg` package
+ * (the host owns the driver; the SDK ships no `pg` in its dependencies).
+ */
+interface SdkPool {
+    query<T = Record<string, unknown>>(text: string, params?: ReadonlyArray<unknown>): Promise<SdkQueryResult<T>>;
+}
+/**
+ * Canonicalize an email to the single casing every key-bearing path agrees on (lowercase, trimmed).
+ *
+ * Email addresses are case-insensitive in practice, but the SDK keys `sdk_contacts.email`,
+ * `sdk_topic_consent.contact`, and `sdk_enrollments.contact` on the email verbatim — while the
+ * webhook resolves with `lower(email)`. A mixed-case enrollment (`Mixed.Case@x.com`) therefore
+ * never matched a lowercased webhook unsubscribe, and the gate read a different row than the one
+ * the host wrote. Normalizing at the single boundary (enroll, consent.set, gate, and the webhook
+ * resolve all call this) makes every path key on the same string, so suppression converges.
+ *
+ * A non-string / empty value is returned as the empty string; callers that require a non-empty
+ * email validate that separately.
+ */
+declare function normalizeEmail(email: string): string;
+/**
+ * A pool wrapper bound to one install namespace. All key-bearing writes/reads go through
+ * `namespaceKey` so rows are isolated per install. Construct one with `createDb`.
+ */
+declare class NamespacedDb {
+    readonly namespace: string;
+    private readonly pool;
+    constructor(pool: SdkPool, namespace: string);
+    /**
+     * Prefix a bare logical key with this install's namespace. The same bare key under two
+     * different namespaces yields two distinct stored keys (KTD7). Callers store/read the
+     * RESULT of this, never the bare key.
+     */
+    namespaceKey(key: string): string;
+    /**
+     * Strip this install's namespace prefix off a stored key, returning the bare key. Throws if
+     * the stored key belongs to a different namespace — a cross-namespace read is a fail-loud
+     * condition (R38), not something to silently paper over.
+     */
+    stripNamespace(storedKey: string): string;
+    /**
+     * Raw query passthrough. Returns the full result so callers can inspect `rows`. Use this for
+     * SELECTs and for writes where you want the returned rows; prefer `execWrite` when you only
+     * need "did it affect a row".
+     */
+    query<T = Record<string, unknown>>(text: string, params?: ReadonlyArray<unknown>): Promise<SdkQueryResult<T>>;
+    /**
+     * Run a write and report success from `rows.length` (invariant 1). The SQL MUST use
+     * `RETURNING` so an effective write yields ≥1 row. Returns the affected count and rows.
+     *
+     * This is the canonical "did the write land" helper: a CAS gate / claim-on-conflict
+     * (`INSERT … ON CONFLICT DO NOTHING RETURNING …`) returns 0 rows when it lost the race,
+     * ≥1 when it won — derived from `rows.length`, never `rowCount`.
+     */
+    execWrite<T = Record<string, unknown>>(text: string, params?: ReadonlyArray<unknown>): Promise<{
+        count: number;
+        rows: T[];
+    }>;
+}
+/**
+ * Construct a namespaced DB wrapper around a host-supplied pool. This is the single entry
+ * point the rest of the SDK uses to reach Postgres.
+ */
+declare function createDb(pool: SdkPool, namespace: string): NamespacedDb;
+
+interface MigrateOptions {
+    /** Override the directory the `.sql` files are read from (tests). Defaults to the shipped dir. */
+    migrationsDir?: string;
+    /** Sink for progress logging. Defaults to a no-op (secrets/PII never flow here, but stay quiet). */
+    log?: (message: string) => void;
+}
+interface MigrateResult {
+    /** Number of migration files applied on this run (0 when already up to date). */
+    applied: number;
+    /** Versions applied on this run, in order. */
+    versions: string[];
+}
+/**
+ * Apply all pending SDK migrations to the host-supplied pool, idempotently.
+ *
+ * Each file runs inside its own transaction (BEGIN/COMMIT, ROLLBACK on error) so a partial DDL
+ * failure rolls back atomically and never half-applies a migration. The tracking insert is part
+ * of the same transaction, so a file is recorded applied only if its DDL committed.
+ *
+ * Returns the count + versions applied — derived from work actually done, not a driver `rowCount`.
+ */
+declare function migrate(pool: SdkPool, options?: MigrateOptions): Promise<MigrateResult>;
+
+/**
+ * A lazily-constructed Resend client bound to one API key. Constructed at most once on first
+ * `client()` call. When the key is empty/undefined the handle is permanently disabled: `enabled`
+ * is `false` and `client()` returns `null` so callers no-op rather than throw.
+ */
+interface ResendClientHandle {
+    /** True when an API key was supplied — i.e. Resend calls will actually be attempted. */
+    readonly enabled: boolean;
+    /**
+     * The underlying Resend client, constructed lazily on first call. Returns `null` when disabled
+     * (no key) so callers can `if (!c) return;` to no-op. Never throws for a missing key — that
+     * decision is surfaced as `enabled === false`, not an exception.
+     */
+    client(): Resend | null;
+}
+/**
+ * Build a lazy Resend handle. `apiKey` is read once here and never logged or stored anywhere it
+ * could be serialized (it lives only inside the closure / the constructed client). Pass the raw
+ * `resendApiKey` from `createEnvoy` config (which itself comes from an env secret per R43).
+ */
+declare function createResendClientHandle(apiKey: string | undefined): ResendClientHandle;
+
+/**
+ * Managed-Agents configuration (R24). Agent id + environment are SDK-level config supplied by the
+ * host from env secrets — never per-tenant DB state. Optional: a pure broadcast/digest host that
+ * runs no AI drip lane needs none of it.
+ */
+interface EnvoyAgentConfig {
+    /** The Claude Managed Agent id that writes per-recipient drip copy. */
+    agentId: string;
+    /** The Managed-Agents environment id. */
+    environmentId: string;
+}
+/**
+ * Per-stream defaults. A "stream" is a type-of-email lane (e.g. `digest`, `alert`) — it scopes the
+ * `List-Unsubscribe` token (R33/R46) and the Topic granularity (R27). The map keys are stream
+ * names; for now the only declared default is the `from` address used when a send omits one.
+ */
+interface EnvoyStreamConfig {
+    /** Default From address for sends on this stream (host may still override per send). */
+    from?: string;
+}
+/**
+ * The config a host passes to `createEnvoy`. Secrets here originate from env (R43) and are never
+ * logged or serialized by the SDK.
+ */
+interface EnvoyConfig {
+    /**
+     * The host-supplied `pg`-compatible pool. The SDK never opens its own connection (R5); all DB
+     * access goes through the namespaced wrapper built from this.
+     */
+    db: SdkPool;
+    /**
+     * Install namespace (R38/KTD7). Prefixes every program/subject/contact key and is
+     * fingerprint-checked. A staging/prod split on one database is two namespaces (two installs).
+     * Must be a non-empty string with no `:` (the namespace key separator).
+     */
+    installNamespace: string;
+    /**
+     * Resend API key (R43). Unlike the other secrets this is NOT required: when unset the Resend
+     * client is a no-op (mirrors the app mailer; lets a host run in dev/CI without a key). Compliance
+     * secrets below ARE required because an unset one is a silent compliance hole, not a dev no-op.
+     */
+    resendApiKey?: string;
+    /** Svix/Resend webhook signing secret (R41). Required — an unset secret is an unverified webhook. */
+    webhookSecret: string;
+    /** Cron secret (R40). Required — an unset secret is an unauthenticated send + generation trigger. */
+    cronSecret: string;
+    /** Unsubscribe-token HMAC secret (R33). Required — an unset secret is an unsigned opt-out link. */
+    unsubscribeSecret: string;
+    /** The base Resend Segment id every enrolled contact joins (R10). Required broadcast target (R17). */
+    baseSegmentId: string;
+    /** Optional Managed-Agents config (R24). Omit for a host that runs no AI drip lane. */
+    agent?: EnvoyAgentConfig;
+    /**
+     * Allow-list of contact `data` fields projected into the agent personalization payload (R44).
+     * The SDK forwards ONLY these fields to Anthropic — never the whole mirror `data` verbatim.
+     * Defaults to an empty list (forward nothing) so the safe default is the privacy-preserving one.
+     */
+    aiFieldAllowList?: string[];
+    /** Per-stream defaults keyed by stream name (R33/R27). Optional. */
+    streams?: Record<string, EnvoyStreamConfig>;
+}
+/** The validated, normalized config the rest of the SDK reads. Secrets are present but the handle
+ * that wraps this never serializes them (see `Envoy.toJSON`). */
+interface ResolvedEnvoyConfig {
+    installNamespace: string;
+    resendApiKey?: string;
+    webhookSecret: string;
+    cronSecret: string;
+    unsubscribeSecret: string;
+    baseSegmentId: string;
+    agent?: EnvoyAgentConfig;
+    /** Frozen, de-duplicated allow-list. Empty array = forward nothing. */
+    aiFieldAllowList: readonly string[];
+    /** Frozen stream-defaults map (empty object when none supplied). */
+    streams: Readonly<Record<string, EnvoyStreamConfig>>;
+}
+/**
+ * The root SDK handle returned by `createEnvoy`. Later units hang their server functions off this
+ * (enroll, sequences, broadcast, send.transactional, …). U3 ships the foundation: the resolved
+ * config, the namespaced DB, the lazy Resend handle, the namespace guard, and the redaction helper.
+ */
+interface Envoy {
+    /** Validated config (defaults applied). Reading secrets off this is intentional for internal
+     * units; the handle's own `toJSON`/inspect output redacts them. */
+    readonly config: ResolvedEnvoyConfig;
+    /** Namespaced DB wrapper bound to `installNamespace`. The single DB boundary for the SDK. */
+    readonly db: NamespacedDb;
+    /** Lazy Resend client handle (no-op when `resendApiKey` is unset). */
+    readonly resend: ResendClientHandle;
+    /**
+     * Verify (and, on first run, write) this install's namespace fingerprint in the host DB (R38).
+     * Idempotent: re-running with the same namespace + identity is a no-op; a namespace already
+     * fingerprinted with a DIFFERENT config identity throws (another install detected). Call this
+     * from the host's init/deploy step; SDK server fns also call it lazily before first DB write.
+     */
+    assertNamespaceFingerprint(): Promise<void>;
+    /**
+     * Redact a secret-bearing or PII-bearing string for logs (R43). Emails are reduced to a
+     * non-reversible hint (`a***@example.com`); any other value is fully masked. Never returns the
+     * original. Use this at every log site that might otherwise emit a secret or full address.
+     */
+    redact(value: unknown): string;
+}
+/** A configuration error thrown by `createEnvoy` at INIT time. Carries no secret values. */
+declare class EnvoyConfigError extends Error {
+    constructor(message: string);
+}
+/** Thrown by `assertNamespaceFingerprint` when the host DB is already owned by an install whose
+ * config identity differs from this one (R38 cross-install guard). */
+declare class EnvoyNamespaceError extends Error {
+    constructor(message: string);
+}
+/**
+ * Reduce an email to a non-reversible hint for logs: `marko@example.com` -> `m***@example.com`.
+ * A malformed / non-email string is fully masked. No full local-part ever appears (R43: "no full
+ * email addresses … appear in logs").
+ */
+declare function redactEmail(value: string): string;
+/**
+ * Best-effort redaction for an arbitrary log value. If it looks like an email, hint it; otherwise
+ * mask it entirely. This is intentionally conservative — when in doubt, mask.
+ */
+declare function redactValue(value: unknown): string;
+/**
+ * Validate + normalize raw host config into a resolved config. Throws `EnvoyConfigError` on the
+ * first problem. Pure (no I/O) so config errors are guaranteed to precede any DB/Resend contact.
+ */
+declare function resolveConfig(cfg: EnvoyConfig): ResolvedEnvoyConfig;
+/**
+ * Derive the install's config-identity fingerprint. It is a hash of the namespace and the stable,
+ * non-secret config identity (`baseSegmentId`) — NOT of any secret (so the stored value leaks
+ * nothing). Two installs that (mis)use the same namespace but target different base Segments produce
+ * different fingerprints and trip the guard; the same install re-running produces the same value
+ * (idempotent). Secrets are intentionally excluded: rotating a key must not trip the guard.
+ */
+declare function computeNamespaceFingerprint(config: ResolvedEnvoyConfig): string;
+/**
+ * Build the root SDK handle. Validates config synchronously (errors thrown here, never at send
+ * time). The namespace fingerprint is checked lazily — the first `assertNamespaceFingerprint()`
+ * call performs the DB write/verify and memoizes the result, so repeated calls cost one round trip.
+ */
+declare function createEnvoy(cfg: EnvoyConfig): Envoy;
+
+/**
+ * The two delivery streams a topic can carry. A "stream" is a type-of-email lane: `digest` is the
+ * recurring/marketing cadence, `alert` is event-triggered. They share a topic row but have
+ * independent consent so opting out of one never silences the other (R27/R33).
+ */
+type Stream = "digest" | "alert";
+/** All streams, in a stable order. Used when an `unsubscribed` write must touch every stream. */
+declare const STREAMS: readonly Stream[];
+/**
+ * Per-stream consent state, mirroring Resend's `'opt_in' | 'opt_out'` subscription plus the SDK's
+ * own terminal `'unsubscribed'`.
+ *
+ * - `opt_in` — receiving this stream of this topic (the default; topics are created public + opt_in).
+ * - `opt_out` — topic-scoped opt-out for this stream; the recipient still receives OTHER topics.
+ * - `unsubscribed` — terminal: the recipient asked to stop everything. Dominates all streams of
+ *   this topic and is mirrored into the contact's global `unsubscribed` flag (R26 suppress-all).
+ */
+type ConsentStatus = "opt_in" | "opt_out" | "unsubscribed";
+/**
+ * A row of the consent mirror for one `(contact, topic)`. `digest`/`alert` are the per-stream
+ * states; `topicId` is the cached Resend Topic id (null until provisioned, U7); `dirty` is true
+ * when the mirror and Resend may have diverged and the reconcile sweep should repair this row.
+ */
+interface ConsentRow {
+    contact: string;
+    topicKey: string;
+    topicId: string | null;
+    digest: ConsentStatus;
+    alert: ConsentStatus;
+    dirty: boolean;
+}
+/** Arguments to `consent.set` — the single write path into the mirror (origin R26/R28). */
+interface ConsentSetInput {
+    /** Recipient email (the logical contact key; namespace-prefixed at the DB boundary). */
+    email: string;
+    /** The topic this consent applies to (host-meaningful key, e.g. `weekly-digest`). */
+    topicKey: string;
+    /** Which stream of the topic to set. */
+    stream: Stream;
+    /** Target consent. `unsubscribed` dominates BOTH streams + the global flag (R26). */
+    status: ConsentStatus;
+    /**
+     * Cached Resend Topic id, if known by the caller (U7 provisioning). When provided it is stored
+     * so the push + reconcile can address the topic; when omitted the push is skipped (no topic id =
+     * nothing to push) and the row is marked dirty for the reconcile sweep to resolve.
+     */
+    topicId?: string | null;
+}
+/** Outcome of a `consent.set` — whether the mirror changed and whether the Resend push confirmed. */
+interface ConsentSetResult {
+    /** The resulting mirror row (post-merge). */
+    row: ConsentRow;
+    /** True when the write actually changed stored state (false = a stale/no-op merge). */
+    changed: boolean;
+    /**
+     * `confirmed` — the Resend `contacts.topics.update` push succeeded and the row is clean.
+     * `skipped` — no Resend (key unset) or no topic id; nothing pushed, row left clean (digest path)
+     *   or dirty (no topic id, needs reconcile).
+     * `dirty` — the push was attempted and FAILED; the row is marked reconcile-dirty (R28: never
+     *   throw into the caller on a push failure; mark dirty and let reconcile repair).
+     */
+    push: "confirmed" | "skipped" | "dirty";
+}
+/**
+ * The consent mirror, bound to one install's namespaced DB + Resend handle. Build via `createConsentMirror`.
+ */
+declare class ConsentMirror {
+    private readonly db;
+    private readonly resend;
+    constructor(db: NamespacedDb, resend: ResendClientHandle);
+    /**
+     * Read the mirror row for `(email, topicKey)`, or `null` if the contact has never been seen for
+     * this topic. This is a pure read — it does NOT create a default row (a missing row means the
+     * topic was never provisioned for this contact; the gate treats that as deny-by-default).
+     */
+    read(email: string, topicKey: string): Promise<ConsentRow | null>;
+    /**
+     * Read the contact-level GLOBAL suppression flag (`sdk_contacts.unsubscribed`), case-insensitively
+     * on the bare email (matches the webhook/`set` convention). A bounce, complaint, GDPR delete, or
+     * hosted-page unsubscribe sets this flag; the gate must honor it on EVERY topic/stream — including
+     * topics for which no per-topic consent row exists — so a globally-suppressed contact can never be
+     * re-addressed on any lane (R22/R26 suppress-all). Returns true when the contact is suppressed.
+     */
+    private isGloballySuppressed;
+    /**
+     * Authoritative send gate (R26). Returns `true` only when this exact stream of this topic is
+     * allowed to send to this contact. Denies when:
+     *   - the contact is GLOBALLY suppressed (`sdk_contacts.unsubscribed = TRUE` — bounce, complaint,
+     *     GDPR delete, or hosted-page unsubscribe), regardless of any per-topic consent, or
+     *   - the contact has no mirror row for the topic (never provisioned → deny-by-default), or
+     *   - the requested stream is `opt_out` or `unsubscribed`, or
+     *   - EITHER stream is `unsubscribed` (the global "everything" suppress dominates both streams).
+     *
+     * The gate reads the local mirror only — never Resend — so it is cheap and deterministic.
+     * Reconcile (U14) is what keeps the mirror honest against Resend's hosted page.
+     */
+    gate(email: string, topicKey: string, stream: Stream): Promise<boolean>;
+    /**
+     * The single consent write path (origin R26/R28). Writes the mirror FIRST (monotonic-merge
+     * upsert), THEN awaits the Resend `contacts.topics.update` push so an unsubscribe is confirmed
+     * before the caller proceeds. A push failure marks the row reconcile-dirty and is reported in
+     * the result — it never throws into the caller (fail-soft external sync).
+     *
+     * Monotonic merge: the stored stream value only moves toward MORE suppression. A stale `opt_in`
+     * against a stored `unsubscribed`/`opt_out` is a no-op (`changed: false`). An `unsubscribed`
+     * write dominates BOTH streams and sets the contact's global suppression flag (R26 suppress-all).
+     */
+    set(input: ConsentSetInput): Promise<ConsentSetResult>;
+}
+/** Construct a consent mirror bound to a namespaced DB + Resend handle. */
+declare function createConsentMirror(db: NamespacedDb, resend: ResendClientHandle): ConsentMirror;
+declare const CONSENT_RANK: Readonly<Record<ConsentStatus, number>>;
+
+/** One step of a drip sequence. */
+interface SequenceStep {
+    /** Saved Resend Template id this step sends (`emails.send({ template: { id } })`, R12). */
+    templateId: string;
+    /**
+     * Time-based wait before this step is eligible, in days, resolved against the cron clock (R15).
+     * `0` ⇒ eligible immediately on reaching the step. Fractional values are allowed (e.g. `0.5` =
+     * 12h). Must be ≥ 0.
+     */
+    waitDays: number;
+    /**
+     * The Template variable names the AI fills at send time (R12/R14). Each must exist as a variable
+     * on the referenced Template — verified by `envoy.validate()` (U18), not here. May be empty for a
+     * non-AI step (a fully static Template).
+     */
+    aiSlots: readonly string[];
+    /** The per-step personalization brief the agent is given (R12). May be empty when `aiSlots` is. */
+    brief: string;
+}
+/** A defined, validated drip sequence. Immutable. */
+interface Sequence {
+    /** Stable sequence key (the `sequence_key` an enrollment is scoped to). */
+    readonly key: string;
+    /** The ordered steps. Index is the step's position (`sdk_steps.step_index`). */
+    readonly steps: readonly Readonly<SequenceStep>[];
+}
+/** Inputs to {@link defineSequence}. */
+interface DefineSequenceInput {
+    key: string;
+    steps: SequenceStep[];
+}
+/** Raised when a sequence definition is malformed (fail loud at definition time). */
+declare class SequenceDefinitionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Define a drip sequence (R12/R13/R15). Validates loud: a missing key, an empty step list, a bad
+ * templateId, a negative wait, or a malformed slot declaration throws `SequenceDefinitionError`.
+ * Returns a frozen `Sequence` whose steps are positionally indexed (`step_index`).
+ */
+declare function defineSequence(input: DefineSequenceInput): Sequence;
+
+/** A claimed due step the engine acts on (the cron tick joins enrollment + step and passes this). */
+interface DueStep {
+    /** `sdk_enrollments.id`. */
+    enrollmentId: number | string;
+    /** `sdk_steps.id` for the current step row (created/looked-up by the tick). */
+    stepId: number | string;
+    /** The recipient email (bare; namespaced only at the DB boundary). */
+    email: string;
+    /** The sequence key the enrollment is scoped to. */
+    sequenceKey: string;
+    /** The 0-based index of the current step (`sdk_enrollments.current_step` / `sdk_steps.step_index`). */
+    stepIndex: number;
+    /** The contact's host `data` snapshot (`sdk_enrollments.data`) — allow-list-filtered before the agent. */
+    data: Record<string, unknown>;
+    /**
+     * Inflight crash-resume marker (`sdk_steps.agent_session_id`). Non-null ⇒ a prior tick started a
+     * session for this exact step — harvest it, never fork a second billed one.
+     */
+    agentSessionId: string | null;
+    /** When the current step became eligible (`sdk_enrollments.next_run_at`). Null ⇒ eligible now. */
+    nextRunAt: Date | string | null;
+}
+/** Why a step did not send (when `sent` is false). */
+type DripSkipReason = "not_due" | "suppressed" | "resend_disabled" | "deferred" | "generation_failed" | "send_failed";
+/** Outcome of {@link runDripStep}. */
+type DripStepResult = {
+    sent: true;
+    emailId: string;
+    advancedTo: number;
+    completed: boolean;
+} | {
+    sent: false;
+    reason: DripSkipReason;
+    detail?: string;
+};
+/** Config the engine needs beyond the Envoy handle. */
+interface DripEngineConfig {
+    /** The consent mirror to gate against (U6). */
+    mirror: ConsentMirror;
+    /** Absolute https landing URL the List-Unsubscribe header points at (R33). */
+    unsubscribeBaseUrl: string;
+    /**
+     * The stream drip steps send on. Defaults to `"digest"` — drip sequences are opt-in nurture, not
+     * transactional alerts. Host can override per program.
+     */
+    stream?: Stream;
+    /** Per-call agent timeout override. */
+    agentTimeoutMs?: number;
+}
+/**
+ * Run one due drip step (R12–R16, R23). Order is load-bearing:
+ *
+ *   1. Resolve the current step from the sequence; an out-of-range index ⇒ complete the enrollment.
+ *   2. Honor the wait (R15) — a not-yet-eligible step is skipped (`not_due`), nothing touched.
+ *   3. GATE against the mirror (R26) — a suppressed contact is never sent (`suppressed`).
+ *   4. Resolve From — fail loud (caller's fail-soft wraps this) if neither default is configured.
+ *   5. Generate-or-harvest the declared slots (R14/R23). A re-claim with a `running` prior session
+ *      DEFERS (no second billed session); a `completed` one is harvested. A failure leaves the step
+ *      due (`generation_failed`) — NOTHING is sent.
+ *   6. No Resend key ⇒ silent no-op (`resend_disabled`, R43) — the step stays due.
+ *   7. `emails.send({ template: { id, variables }, headers: List-Unsubscribe }, { idempotencyKey })`
+ *      — the idempotency key is the REQUEST OPTION (`Idempotency-Key` header), never a body field.
+ *   8. Only on a confirmed send: mark the step sent + advance the enrollment (R16). A send failure
+ *      leaves the step due (`send_failed`).
+ */
+declare function runDripStep(envoy: Envoy, sequence: Sequence, due: DueStep, config: DripEngineConfig, now?: Date): Promise<DripStepResult>;
+/**
+ * Resolves a sequence definition by key. The host registers every `defineSequence(...)` it runs and
+ * passes this lookup to the tick — the SDK never persists sequence definitions (they live in host
+ * code, R12), only enrollment/step STATE. An enrollment whose `sequence_key` is not registered is
+ * skipped (`unknown_sequence`) rather than silently dropped — a deploy that removed a sequence still
+ * in flight is a host bug we surface, not bury.
+ */
+type SequenceRegistry = ReadonlyMap<string, Sequence> | ((sequenceKey: string) => Sequence | undefined);
+/** Per-enrollment outcome the tick collects (one entry per CLAIMED enrollment). */
+interface DripTickItem {
+    enrollmentId: number | string;
+    email: string;
+    sequenceKey: string;
+    stepIndex: number;
+    /** The engine outcome, or a tick-level skip the engine never sees. */
+    result: DripStepResult | {
+        sent: false;
+        reason: "unknown_sequence" | "tick_error";
+        detail?: string;
+    };
+}
+/** Aggregate result of one cron tick. Counts are derived from the per-item outcomes. */
+interface DripTickResult {
+    /** How many due enrollments this tick claimed (0 ⇒ nothing was due / all were locked by a peer). */
+    claimed: number;
+    /** How many claimed steps actually sent an email. */
+    sent: number;
+    /** How many were skipped (not_due / suppressed / deferred / unknown_sequence / resend_disabled). */
+    skipped: number;
+    /** How many failed (generation_failed / send_failed / tick_error) — left due for a later tick. */
+    failed: number;
+    /** Per-enrollment detail (bounded by `limit`). */
+    items: DripTickItem[];
+}
+/** Options for {@link tickDrip}. */
+interface DripTickConfig extends DripEngineConfig {
+    /** Max due enrollments to claim per tick (bounds one invocation's work / `maxDuration`). */
+    limit?: number;
+}
+/**
+ * Run one cron tick of the drip lane (R20, R21). The mounted cron sub-path (U9 handler) calls this
+ * after CRON_SECRET auth (U4). It:
+ *
+ *   1. Atomically claims up to `limit` due enrollments (SKIP LOCKED) — the SELECTION guard.
+ *   2. For each, resolves the sequence from the host registry (unknown ⇒ skip, never drop).
+ *   3. Ensures the current step's row exists (carrying any inflight marker) and builds a `DueStep`.
+ *   4. Runs `runDripStep` — generate-or-harvest → gate → send → advance, all fail-safe (R16).
+ *
+ * PER-CONTACT FAIL-SOFT (R21): one enrollment's thrown error (a registry callback that throws, a
+ * step-row write that errors) is caught, recorded as a `tick_error` item, and the tick CONTINUES —
+ * one bad contact never aborts the others. The enrollment is left due (untouched), so it retries.
+ */
+declare function tickDrip(envoy: Envoy, registry: SequenceRegistry, config: DripTickConfig, now?: Date): Promise<DripTickResult>;
+
+/**
+ * Result a sub-handler must return: an App-Router-compatible `Response`. Sub-handlers receive the
+ * raw `Request` (already authenticated by the factory) plus the parsed sub-path tail.
+ */
+type SubHandler = (request: Request) => Response | Promise<Response>;
+/**
+ * Host `authorize(req)` callback (R6). The host owns identity; the SDK ships no login/session.
+ *
+ * CONTRACT — the return value is interpreted strictly:
+ *   - `true`  ⇒ authorized; the request proceeds to the sub-handler. The boolean `true` is the
+ *               ONLY value that grants access. Nothing else does.
+ *   - a `Response` ⇒ a DENIAL channel ONLY. A non-2xx `Response` (e.g. a custom 401/403/redirect)
+ *               is returned to the client verbatim. A 2xx `Response` is a host CONTRACT ERROR — an
+ *               `authorize` callback must never signal "allowed" by returning a success Response —
+ *               so the factory treats it as unauthorized (a generic 401), NEVER as authorized. This
+ *               fail-closed reading means a host that accidentally returns `new Response("ok")` from
+ *               authorize cannot open its entire API surface (an ambiguous-host-return admit).
+ *   - any other falsy value (`false`, `undefined`, `null`) ⇒ a generic 401.
+ */
+type Authorize = (request: Request) => AuthorizeResult | Promise<AuthorizeResult>;
+type AuthorizeResult = boolean | Response;
+/**
+ * Config for `createEnvoyHandler`. Every authenticated sub-path is optional EXCEPT the auth
+ * mechanism that guards it. A sub-path with no handler still authenticates first, then returns 501
+ * — so an attacker can never tell "unimplemented" from "unauthorized" without first passing auth.
+ */
+interface EnvoyHandlerConfig {
+    /** The root SDK handle (supplies `config.cronSecret`, `config.webhookSecret`, DB, redaction). */
+    envoy: Envoy;
+    /**
+     * Host authorization for the `/api` and `/read` sub-paths (R6). Required: the API surface must
+     * not be open. cron/webhook/unsubscribe/mcp do NOT use this — they carry no host session.
+     */
+    authorize: Authorize;
+    /**
+     * Dedicated MCP credential (R42). The `/mcp` sub-path is independently authenticated against
+     * this secret with a constant-time compare. When omitted, `/mcp` fails closed (401) — it is
+     * NEVER open.
+     */
+    mcpSecret?: string;
+    /**
+     * `"dev"` relaxes the unset-`CRON_SECRET` guard to allow unauthenticated cron locally (mirrors
+     * the app's dev-only allowance). In any other environment an unset cron secret fails closed.
+     * Defaults to `"prod"` (fail-closed) when omitted — safe by default.
+     */
+    environment?: string;
+    /** Handler for `/api/*` (authenticated by `authorize`). */
+    api?: SubHandler;
+    /** Handler for `/read/*` (authenticated by `authorize`). Read-only host endpoints (hooks, U17). */
+    read?: SubHandler;
+    /** Handler for `/cron/*` (authenticated by `CRON_SECRET`). The drip/broadcast tick driver. */
+    cron?: SubHandler;
+    /** Handler for `/webhook/*` (authenticated by Svix). The Resend event ingest (U5). */
+    webhook?: SubHandler;
+    /** Handler for `/unsubscribe/*` (self-authenticating signed token, U6). */
+    unsubscribe?: SubHandler;
+    /** Handler for `/mcp/*` (authenticated by `mcpSecret`). The MCP endpoint (U16). */
+    mcp?: SubHandler;
+}
+/** App Router route module shape: a `{ GET, POST }` pair of request handlers. */
+interface EnvoyRouteHandlers {
+    GET: SubHandler;
+    POST: SubHandler;
+}
+/** Known sub-paths. Anything else is a 404 (we never leak which unknown paths exist). */
+declare const KNOWN_SUBPATHS: readonly ["api", "read", "cron", "webhook", "unsubscribe", "mcp"];
+type KnownSubpath = (typeof KNOWN_SUBPATHS)[number];
+/**
+ * Extract the dispatch sub-path segment from a request URL. The factory is mount-agnostic: the host
+ * mounts the catch-all anywhere (`/api/envoy/...`, `/envoy/...`, etc.), so the SDK cannot know the
+ * base length. The dispatch segment is the one the host appended AFTER the mount base, so we scan
+ * for the LAST segment that matches a known sub-path — the deepest match is the action segment,
+ * never a coincidental `api` in the mount base (e.g. `/api/envoy/cron/tick` → `cron`, and
+ * `/api/envoy/api/enroll` → the second `api`). If no known segment appears, the sub-path is
+ * `null` ⇒ 404. A trailing extra path after the sub-path (`/webhook/resend`) still resolves to
+ * `webhook` because that is the last KNOWN segment.
+ */
+declare function resolveSubpath(url: string): KnownSubpath | null;
+/**
+ * Build the mounted route handlers. The host wires the returned `{ GET, POST }` into a single
+ * catch-all App Router route. Both verbs share one dispatcher; each sub-handler decides which
+ * methods it accepts. Auth is enforced per sub-path before any handler body runs (KTD8).
+ */
+declare function createEnvoyHandler(config: EnvoyHandlerConfig): EnvoyRouteHandlers;
+/** Config for {@link createDripCronHandler}. */
+interface DripCronHandlerConfig {
+    /** The root SDK handle (DB, Resend, agent, redaction). */
+    envoy: Envoy;
+    /**
+     * How the tick resolves a sequence definition by key — a `Map` of `key → Sequence`, or a lookup
+     * function. Sequence definitions live in host code (`defineSequence`), never in the DB, so the
+     * host must register every sequence it runs. An enrollment whose key is not registered is skipped,
+     * not dropped.
+     */
+    registry: SequenceRegistry;
+    /** Engine config (consent mirror, unsubscribe base URL, stream, per-tick limit). */
+    tick: DripTickConfig;
+}
+/**
+ * The JSON body the drip cron handler returns on a successful tick. This is the WIRE shape the host
+ * types its cron route against — deliberately distinct from the engine's {@link DripTickResult}, which
+ * additionally carries the bounded per-enrollment `items[]`. The handler intentionally returns ONLY the
+ * aggregate counts (no `items`), so hosts must not be forced to satisfy a required `items` field that the
+ * response never includes.
+ */
+interface CronTickResponse {
+    /** Always `true` on the 200 path (a thrown tick surfaces `{ ok: false, error }` with a 500). */
+    ok: true;
+    /** How many due enrollments this tick claimed. */
+    claimed: number;
+    /** How many claimed steps actually sent an email. */
+    sent: number;
+    /** How many were skipped (not_due / suppressed / deferred / unknown_sequence / resend_disabled). */
+    skipped: number;
+    /** How many failed (generation_failed / send_failed / tick_error) — left due for a later tick. */
+    failed: number;
+}
+/**
+ * Build the `/cron/drip` handler. Returns a {@link SubHandler} — `(request) => Promise<Response>` —
+ * the host passes to `createEnvoyHandler({ ..., cron })`. The factory already gated the request on
+ * `CRON_SECRET`; this handler runs one tick and returns a JSON summary (claimed/sent/skipped/failed).
+ *
+ * It NEVER throws to the caller: a claim/DB error is caught, redacted, logged, and surfaced as a 500
+ * so the host's cron platform retries — but a single contact's failure inside the tick is already
+ * fail-soft (R21) and reported in the body, not raised. A 2xx is returned even when some items
+ * failed (they are left due and retried next tick); the body carries the breakdown for host alerting
+ * (e.g. `lastFiredAt`-style health, R36 spirit).
+ */
+declare function createDripCronHandler(config: DripCronHandlerConfig): (request: Request) => Promise<Response>;
+
+/** Minimum token lifetime: 60 days. CAN-SPAM requires an opt-out mechanism that stays live for at
+ * least 30 days post-send; RFC 8058 one-click links are long-lived. We floor at 60d and reject any
+ * caller-supplied TTL below it (a too-short link is a compliance hole, fail loud at build time). */
+declare const MIN_UNSUBSCRIBE_TTL_SECONDS: number;
+/** The signed claims inside an unsubscribe token. `exp` is a Unix epoch SECONDS expiry. */
+interface UnsubscribeClaims {
+    /** Bare recipient email (the contact key). */
+    contact: string;
+    /** Topic the opt-out applies to. */
+    topicKey: string;
+    /** Stream of the topic the opt-out applies to. */
+    stream: Stream;
+    /** Expiry, Unix epoch seconds. */
+    exp: number;
+}
+/** Result of verifying a token: the claims on success, or a reason on failure. Callers MUST NOT
+ * surface the reason to the client (uniform responses / no oracle) — it is for internal logging
+ * only, and even then the contact is redacted at the log site. */
+type VerifyResult = {
+    ok: true;
+    claims: UnsubscribeClaims;
+} | {
+    ok: false;
+    reason: "malformed" | "bad_signature" | "expired";
+};
+/**
+ * Verify a token against the secret with a constant-time signature compare and an expiry check.
+ * Returns the decoded claims on success. NEVER throws on attacker-controlled input — a malformed
+ * token is a typed failure, not an exception.
+ */
+declare function verifyUnsubscribeToken(token: string, secret: string, nowSeconds?: number): VerifyResult;
+/** Options for minting an unsubscribe token (drip/transactional lane). */
+interface CreateTokenInput {
+    email: string;
+    topicKey: string;
+    stream: Stream;
+    /** Token lifetime in seconds. Defaults to and floored at `MIN_UNSUBSCRIBE_TTL_SECONDS` (60d). */
+    ttlSeconds?: number;
+}
+/**
+ * Mint a signed, expiring, topic+stream-scoped unsubscribe token. Throws if the requested TTL is
+ * below the 60-day compliance floor (fail loud at build time, not silently shorten).
+ */
+declare function createUnsubscribeToken(input: CreateTokenInput, secret: string, nowSeconds?: number): string;
+/** Built RFC 8058 one-click headers for a single `emails.send` call. */
+interface ListUnsubscribeHeaders {
+    "List-Unsubscribe": string;
+    "List-Unsubscribe-Post": string;
+}
+/**
+ * Build the `List-Unsubscribe` + `List-Unsubscribe-Post` headers for a drip/transactional send
+ * (R33). The URL points at the SDK-owned landing under the host's mounted base path. `baseUrl` is
+ * the absolute, already-mounted unsubscribe endpoint (e.g. `https://app.example.com/api/envoy/unsubscribe`);
+ * the token is appended as a query param.
+ *
+ * RFC 8058: the presence of `List-Unsubscribe-Post: List-Unsubscribe=One-Click` tells the MUA the
+ * `List-Unsubscribe` URL accepts a POST one-click. The URL MUST be `https`.
+ */
+declare function buildListUnsubscribeHeaders(input: CreateTokenInput, secret: string, baseUrl: string, nowSeconds?: number): ListUnsubscribeHeaders;
+/** Default unsubscribe-landing rate limit: 20 requests / 60s per client IP. Generous enough for a
+ * real MUA's prefetch + the human's click, tight enough to blunt token-guessing fan-out. */
+declare const DEFAULT_UNSUB_RATE_LIMIT = 20;
+declare const DEFAULT_UNSUB_RATE_WINDOW_SECONDS = 60;
+interface RateLimitResult {
+    allowed: boolean;
+    remaining: number;
+    retryAfterSeconds: number;
+}
+/**
+ * Atomic fixed-window limiter over `sdk_rate_limits`. The window resets when `window_start` ages
+ * past `windowSeconds`, otherwise the counter increments. Allowed while the post-increment count
+ * is within `limit`. FAILS OPEN on a DB error: a limiter outage must not lock every recipient out
+ * of unsubscribing (an unreachable opt-out is itself a compliance failure).
+ */
+declare function checkRateLimit(db: NamespacedDb, bareKey: string, limit: number, windowSeconds: number): Promise<RateLimitResult>;
+/** Best-effort client IP from proxy headers — rate-limit bucket key only, never authorization. */
+declare function clientIp(request: Request): string;
+/** Config the landing handler needs: the verifying secret, the mirror to write the opt-out into,
+ * the namespaced DB for rate-limiting, and optional limiter tunables. */
+interface UnsubscribeLandingConfig {
+    secret: string;
+    mirror: ConsentMirror;
+    db: NamespacedDb;
+    rateLimit?: {
+        limit?: number;
+        windowSeconds?: number;
+    };
+}
+/**
+ * Handle a one-click unsubscribe request (RFC 8058). The token may arrive in the `token` query
+ * param (the `List-Unsubscribe` URL) or, on the POST, in a form-encoded `token` body field (the
+ * interstitial's hidden input).
+ *
+ * Method semantics (the security boundary):
+ *   - GET performs NO write. It renders a small interstitial confirmation page whose button POSTs
+ *     the token back. This makes the SDK safe against link prefetchers, link-unfurlers, and
+ *     security scanners that GET every URL in an email — none of which should ever be able to
+ *     unsubscribe a recipient. The interstitial is identical regardless of token validity (no
+ *     oracle).
+ *   - POST is the mutating one-click action. It verifies the token and, on success, writes a
+ *     TOPIC-SCOPED `opt_out` via the mirror (NOT a global unsubscribe). Forged/expired/malformed →
+ *     uniform 200 blank, NO state change. Already-opted-out is the same response (monotonic no-op).
+ *
+ * Other invariants:
+ *   - Rate-limit by client IP first; over the limit → 429 (uniform, no body detail).
+ *   - Never 500 on attacker input; never redirect.
+ */
+declare function handleUnsubscribe(request: Request, config: UnsubscribeLandingConfig): Promise<Response>;
+
+/** The envelope every Resend webhook shares: a discriminating `type` and a `data` object. */
+interface ResendWebhookEvent {
+    type?: string;
+    created_at?: string;
+    data?: Record<string, unknown>;
+}
+/** Outcome of ingesting one event — returned for assertions/observability; serialized to the body. */
+interface WebhookIngestResult {
+    /** The dispatch branch the event took. */
+    kind: "contact" | "suppression" | "analytics" | "ignored";
+    /** The discriminator that was seen (echoed for diagnostics; never includes PII). */
+    type: string;
+    /** True when a reconcile was enqueued (contact change signal). */
+    reconcileEnqueued: boolean;
+    /** True when a global suppression flag was written. */
+    suppressed: boolean;
+    /** True when the referenced contact existed and was resolved. */
+    contactMatched: boolean;
+}
+/**
+ * Pull a recipient email out of an event's `data`. Contact events carry `data.email`; email events
+ * carry `data.to` (Resend sends an array; we also tolerate a bare string). Returns the FIRST valid
+ * recipient, lowercased+trimmed (so resolution is case-insensitive), or null when none is present.
+ */
+declare function extractRecipientEmail(data: Record<string, unknown> | undefined): string | null;
+/**
+ * Ingest one already-verified, already-parsed Resend webhook event. Pure dispatch + DB writes; it
+ * never throws on an unknown / foreign / unmatched event (R41 ack-and-ignore). Returns a structured
+ * result the route layer serializes into the 200 body.
+ */
+declare function ingestEvent(envoy: Envoy, event: ResendWebhookEvent): Promise<WebhookIngestResult>;
+/**
+ * Build the `/webhook` sub-handler. Wire the returned function as
+ * `createEnvoyHandler({ ..., webhook: createWebhookReceiver(envoy) })`.
+ *
+ * The route factory has already Svix-verified the request and re-exposed the verified raw body, so
+ * this receiver parses + dispatches only. It ALWAYS returns 2xx for a processable or ignorable
+ * event (R41 ack-and-ignore) and never 500s on a malformed body — a 5xx would make Resend retry a
+ * payload we will never accept.
+ */
+declare function createWebhookReceiver(envoy: Envoy): (request: Request) => Promise<Response>;
+
+/**
+ * Canonical topic key for a `(stream, subject)` pair. This is the host-meaningful key stored on
+ * `sdk_topic_consent.topic_key` AND the `sdk_program_state.subject_key` of the provisioning cache,
+ * so the consent mirror and the provisioning cache agree on one identity. `:` is allowed here (it
+ * is only forbidden in the install namespace, not in topic keys).
+ */
+declare function topicKeyFor(stream: Stream, subject: string): string;
+/** Outcome of a provisioning call. `created` distinguishes a fresh Resend Topic from a cache hit. */
+interface ProvisionTopicResult {
+    /** The host-meaningful topic key (`stream:subject`). */
+    topicKey: string;
+    /** The cached Resend Topic id (always present on success). */
+    topicId: string;
+    /** True when this call created the Resend Topic; false when it returned a cached id. */
+    created: boolean;
+}
+/** Inputs to {@link provisionTopic}. */
+interface ProvisionTopicInput {
+    stream: Stream;
+    subject: string;
+}
+/**
+ * Provision (idempotently) the Resend Topic for a `(stream, subject)` pair and cache its id.
+ *
+ * Ordering — cache FIRST, create only on a miss:
+ *   1. Read the cache. A hit returns the cached id with `created: false`, creating nothing (the
+ *      idempotent fast path — the second `provision` of the same pair is a pure read).
+ *   2. On a miss, create the Resend Topic (`opt_in`, public-by-intent), then claim-or-read the
+ *      cache row. If we lost the claim to a concurrent provision, we adopt the winner's id and the
+ *      Topic we created is a harmless duplicate-free no-op (we never persisted its id) — the cache
+ *      holds exactly one id per topic key.
+ *
+ * When Resend is unset (no key) provisioning cannot create a Topic; it returns a cache hit if one
+ * exists, otherwise throws (a topic id is required to address the topic for opt-state pushes — a
+ * silent no-op here would hide a real misconfiguration, unlike a send which fails soft).
+ */
+declare function provisionTopic(db: NamespacedDb, resend: ResendClientHandle, input: ProvisionTopicInput): Promise<ProvisionTopicResult>;
+
+/** Outcome of a segment membership mutation. `ok: false` ⇒ caller should mark the row dirty. */
+interface SegmentOpResult {
+    /** True when Resend confirmed the mutation; false on a Resend error, throw, or unset key. */
+    ok: boolean;
+    /** Present when the op was a no-op because Resend is unset (key absent) — distinct from a failure. */
+    skipped?: boolean;
+    /** A short, non-PII reason on failure (Resend error message or "threw"). Never the email. */
+    reason?: string;
+}
+/**
+ * Add a contact (by email) to a Segment. Fail-soft: a Resend error or thrown transport error
+ * returns `{ ok: false }` rather than throwing into the caller. An unset Resend key returns
+ * `{ ok: false, skipped: true }` (nothing to push; the caller leaves the row dirty for reconcile).
+ */
+declare function addToSegment(resend: ResendClientHandle, email: string, segmentId: string): Promise<SegmentOpResult>;
+/**
+ * Remove a contact (by email) from a Segment. Same fail-soft contract as {@link addToSegment}. Used
+ * by right-to-erasure (R34) best-effort membership teardown.
+ */
+declare function removeFromSegment(resend: ResendClientHandle, email: string, segmentId: string): Promise<SegmentOpResult>;
+
+/** Host-supplied contact: an email plus arbitrary JSON `data` Envoy mirrors verbatim (R9). */
+interface ContactInput {
+    email: string;
+    data?: Record<string, unknown>;
+}
+/** A topic to reflect during a push: identified by `(stream, subject)`, with the opt-state to set. */
+interface SyncTopic {
+    stream: Stream;
+    subject: string;
+    /** Subscription to push for this topic. Defaults to `opt_in` (topics are subscribe-by-default). */
+    subscription?: "opt_in" | "opt_out";
+}
+/** Inputs to a single `sync.push`. */
+interface SyncPushInput {
+    email: string;
+    /** Optional topic to provision + push opt-state for. Omit for a Contact + Segment only push. */
+    topic?: SyncTopic;
+}
+/** Result of a `sync.push`. `ok` is true only when EVERY awaited step confirmed. */
+interface SyncPushResult {
+    ok: boolean;
+    /** True when any step failed and the contact row was marked reconcile-dirty. */
+    dirty: boolean;
+    /** Per-step outcomes for observability (no PII). */
+    steps: {
+        contact: "confirmed" | "failed" | "skipped";
+        segment: "confirmed" | "failed" | "skipped";
+        topic: "confirmed" | "failed" | "skipped" | "none";
+    };
+}
+/**
+ * The push-on-write SegmentSync primitive (R37). Build one per install via {@link createSegmentSync}.
+ * Every `push` upserts the global Contact, adds the contact to the base Segment, and (when a topic
+ * is given) provisions the Topic + pushes its opt-state — ALL AWAITED, fail-soft.
+ */
+declare class SegmentSync {
+    private readonly envoy;
+    constructor(envoy: Envoy);
+    /**
+     * Push a contact's Resend reflection. Order: global Contact upsert → base Segment add → Topic
+     * opt-state. Each step is awaited; a Resend-unset key makes the whole push a silent no-op
+     * (`ok: false`, dirty left for reconcile). Any partial failure marks the contact row dirty and
+     * returns `{ ok: false, dirty: true }` WITHOUT throwing (R37).
+     */
+    push(input: SyncPushInput): Promise<SyncPushResult>;
+}
+/** Construct a SegmentSync bound to an Envoy install. */
+declare function createSegmentSync(envoy: Envoy): SegmentSync;
+/** Result of an {@link enroll}. `created: false` ⇒ an idempotent no-op re-enroll (R11). */
+interface EnrollResult {
+    /** The (bare) contact email. */
+    email: string;
+    /** The sequence the contact is enrolled in. */
+    sequenceKey: string;
+    /** Enrollment status (`active` for a fresh or already-active enrollment). */
+    status: string;
+    /** True when this call created the enrollment; false when it already existed (no-op, R11). */
+    created: boolean;
+    /** True when the contact is globally suppressed — enrollment is recorded but no sync/send occurs. */
+    suppressed: boolean;
+    /** The SegmentSync push outcome, or `null` when skipped (already active, or suppressed). */
+    sync: SyncPushResult | null;
+}
+/** Options for {@link enroll}. */
+interface EnrollOptions {
+    /** Topic to reflect into Resend for this enrollment (provision + opt-state push). */
+    topic?: SyncTopic;
+    /**
+     * The stream the drip lane will send this sequence on (R27). Defaults to `"digest"` — drip
+     * sequences are opt-in nurture, matching the drip engine's `stream` default. Used to seed the
+     * LOCAL consent row the send gate reads, so the gate passes without a separate `consent.set`.
+     */
+    stream?: Stream;
+}
+/**
+ * Enroll a contact into a sequence (R8). Steps:
+ *   1. Upsert the mirror contact (R9). A globally-suppressed contact still records the enrollment
+ *      but performs NO Resend sync and is reported `suppressed: true` (the send gate denies later).
+ *   2. Claim the enrollment row (R11). A FRESH claim (`created: true`) proceeds to sync; an
+ *      already-ACTIVE enrollment is an idempotent no-op (`created: false`, `sync: null`) — nothing
+ *      new is sent (R11).
+ *   3. On a fresh enrollment, run `sync.push` (Contact → base Segment → Topic opt-state), awaited
+ *      and fail-soft (R10/R37).
+ *
+ * Never throws on a Resend failure — the sync result carries the dirty flag. Throws only on a hard
+ * mirror-write failure (a contract violation, not an external-service hiccup).
+ *
+ * Consent seeding (drip-lane correctness): a fresh, non-suppressed enrollment ALSO seeds a LOCAL
+ * `opt_in` consent row for `(email, sequenceKey)` on the drip stream via `mirror.set`. The drip
+ * send gate (U6) reads that local mirror and denies-by-default when no row exists — without this
+ * seed every drip step would be suppressed until the host separately called `consent.set`. The seed
+ * is a monotonic `opt_in`, so it never resurrects a recipient who already unsubscribed.
+ */
+declare function enroll(envoy: Envoy, contact: ContactInput, sequenceKey: string, options?: EnrollOptions): Promise<EnrollResult>;
+/** Result of a {@link deleteContact}. Each best-effort Resend teardown is reported independently. */
+interface DeleteContactResult {
+    email: string;
+    /** True once the mirror was suppressed (always attempted first; throws only on a hard DB failure). */
+    suppressed: boolean;
+    /** The captured Resend contact id (or null when the contact was never reflected to Resend). */
+    resendContactId: string | null;
+    /** Best-effort teardown outcomes. `skipped` ⇒ Resend unset or nothing to delete. */
+    resendContactDeleted: "deleted" | "failed" | "skipped";
+    segmentMembershipRemoved: "removed" | "failed" | "skipped";
+    topicMembershipCleared: "cleared" | "failed" | "skipped";
+    /** True once the contact's enrollment/step PII columns were purged (R34 GDPR erasure). */
+    piiPurged: boolean;
+}
+/**
+ * Host-invoked right-to-erasure (R34). Order is load-bearing:
+ *   1. SUPPRESS THE MIRROR FIRST. This guarantees the next reconcile excludes the contact and a
+ *      stale `topics.list` read cannot reconcile a deleted contact back to active (suppress-before-
+ *      delete). This step is the only one that may throw (a hard DB failure) — everything after is
+ *      best-effort and fail-soft.
+ *   2. Capture the Resend contact id from the mirror (before the row is anything but suppressed).
+ *   3. Best-effort delete the Resend Contact + Segment/Topic membership. Each is independent and
+ *      fail-soft: a Resend error on one does not abort the others, and NONE throw (R34). An already-
+ *      accepted broadcast cannot be recalled — that residual is acknowledged, not handled here.
+ *
+ * Note: the local mirror row is intentionally LEFT in place (suppressed), not hard-deleted — the
+ * SDK never hard-deletes rows (the suppressed mirror is what keeps the contact excluded across both
+ * lanes). The host's own data-retention policy governs purging the mirror row itself.
+ */
+declare function deleteContact(envoy: Envoy, rawEmail: string, options?: {
+    segmentIds?: string[];
+    topicIds?: string[];
+}): Promise<DeleteContactResult>;
+
+/**
+ * Merge variables injected into the Resend Template. resend@6.14.0's `template.variables` is typed
+ * `Record<string, string | number>`; we accept the same so the value passes straight through.
+ */
+type TransactionalVariables = Record<string, string | number>;
+/** Inputs to {@link sendTransactional} (origin R46). */
+interface TransactionalSendInput {
+    /** Recipient email (the contact key; namespace-prefixed only at the DB boundary, not on the wire). */
+    email: string;
+    /** Saved Resend Template id whose variables this send fills (`emails.send({ template: { id } })`). */
+    templateId: string;
+    /**
+     * Template variables to inject. The referenced Template owns all visual structure; these fill its
+     * declared variables. Optional — a Template with no variables needs none.
+     */
+    variables?: TransactionalVariables;
+    /**
+     * Stream this send belongs to (`digest` | `alert`). REQUIRED — it scopes the `List-Unsubscribe`
+     * token (R33/R46). A missing/empty stream is rejected before any Resend contact (R45).
+     */
+    stream: Stream;
+    /**
+     * Topic this send belongs to. Scopes the suppression gate AND the unsubscribe token to a single
+     * `(contact, topic, stream)` so a one-click opt-out leaves the recipient's other topics intact
+     * (R33). Required for the same reason the stream is: a transactional email with no topic has no
+     * place to scope its opt-out.
+     */
+    topicKey: string;
+    /**
+     * Idempotency key forwarded to Resend as the `Idempotency-Key` request HEADER (NOT a body field)
+     * for exactly-once delivery on retry (R46). Optional — a one-shot send may forgo it, but a host
+     * that may retry should always supply a stable key.
+     */
+    idempotencyKey?: string;
+    /**
+     * Sender address. Falls back to the stream's configured `from` default (`createEnvoy`'s
+     * `streams[stream].from`) when omitted. A send with neither is rejected (R45-style fail-loud:
+     * Resend requires a verified From).
+     */
+    from?: string;
+    /** Optional subject override. When omitted the Resend Template's own subject is used. */
+    subject?: string;
+    /** Optional reply-to address(es). */
+    replyTo?: string | string[];
+}
+/** Why a transactional send did not dispatch (when `sent` is false). */
+type TransactionalSkipReason = "suppressed" | "resend_disabled";
+/** Outcome of a {@link sendTransactional}. */
+type TransactionalSendResult = {
+    /** True when Resend accepted the email. */
+    sent: true;
+    /** The Resend email id returned by `emails.send`. */
+    emailId: string;
+} | {
+    sent: false;
+    /** Why nothing was sent. */
+    reason: TransactionalSkipReason;
+};
+/**
+ * Error thrown by {@link sendTransactional} for a HOST-CONTRACT violation it must fail loud on
+ * (missing stream/topic/template/from, or a hard Resend error) — distinct from the fail-soft
+ * `{ sent: false }` outcomes (suppression, no key) which are normal control flow, not errors.
+ */
+declare class TransactionalSendError extends Error {
+    constructor(message: string);
+}
+/** Config the transactional sender needs beyond the Envoy handle. */
+interface TransactionalSendConfig {
+    /** The consent mirror to gate against (U6). */
+    mirror: ConsentMirror;
+    /**
+     * Absolute, already-mounted, `https` unsubscribe landing URL (e.g.
+     * `https://app.example.com/api/envoy/unsubscribe`). The signed token is appended as `?token=…`.
+     * Required — without it there is no place for the `List-Unsubscribe` header to point (R33).
+     */
+    unsubscribeBaseUrl: string;
+}
+/**
+ * Send one transactional (non-AI) templated email through Resend (R46). Order is load-bearing:
+ *
+ *   1. Validate inputs — fail loud on a missing stream/topic/template/email (R45). NOTHING touches
+ *      Resend or the contact before this passes.
+ *   2. Resolve the From address (explicit or stream default) — fail loud if neither.
+ *   3. GATE against the mirror (R26). A suppressed contact returns `{ sent: false, reason:
+ *      "suppressed" }` — no Resend call. The gate reads the mirror only (cheap, deterministic).
+ *   4. If Resend is unset, silent no-op `{ sent: false, reason: "resend_disabled" }` (R43).
+ *   5. Build the RFC 8058 `List-Unsubscribe` headers pointing at the SDK-owned landing (R33).
+ *   6. `emails.send({ template: { id, variables }, to, from, headers, subject? }, { idempotencyKey })`
+ *      — the idempotency key is the REQUEST OPTION (`Idempotency-Key` header), never a body field.
+ *   7. A Resend in-band `error` is a fail-loud `TransactionalSendError` (the host asked to send a
+ *      one-shot email and Resend refused — unlike the drip lane there is no later tick to retry it).
+ */
+declare function sendTransactional(envoy: Envoy, input: TransactionalSendInput, config: TransactionalSendConfig): Promise<TransactionalSendResult>;
+
+/** Error raised by the agent flow. Carries an HTTP-ish status and an optional sanitized detail. */
+declare class AgentError extends Error {
+    readonly status: number;
+    readonly detail?: string;
+    constructor(message: string, status: number, detail?: string);
+}
+/** Per-call options. */
+interface AgentCallOpts {
+    /** Invocation timeout. Defaults to 10 minutes — matches the app's run timeout. */
+    timeoutMs?: number;
+    /**
+     * Invoked with the new session id immediately after `sessions.create` and BEFORE the billed
+     * `events.send` turn. The caller persists it as an inflight crash-resume marker that always
+     * precedes any billed work. If it throws, the un-sent (unbilled) session is archived and the
+     * call fails — we never start a billed turn we cannot track.
+     */
+    onSessionCreated?: (sessionId: string) => void | Promise<void>;
+}
+interface AgentSessionResult {
+    /** The chosen (content-seek) output text. */
+    output: string;
+    /** The session id (already persisted via `onSessionCreated` if supplied). */
+    sessionId: string;
+}
+/**
+ * Lazy Anthropic client singleton. Reads `ANTHROPIC_API_KEY` from env (the deployment-wide key for
+ * the account that owns the Managed Agents). `maxRetries` covers 429 / transient 5xx with the
+ * SDK's built-in exponential backoff. Allows injecting a client for tests.
+ */
+declare function getAgentClient(): Anthropic;
+/** Override the client (tests only). Passing `null` restores lazy construction. */
+declare function setAgentClient(client: Anthropic | null): void;
+/**
+ * Drive one Managed Agents session to completion and return the chosen output text plus the session
+ * id. Persists the marker via `onSessionCreated` BEFORE the billed turn. Throws `AgentError` on
+ * session error (502) or timeout (504).
+ */
+declare function runAgentSession(agentId: string, environmentId: string, userMessage: string, opts?: AgentCallOpts): Promise<AgentSessionResult>;
+/**
+ * Outcome of a crash-resume harvest:
+ *  - `completed`: the prior session finished (`end_turn`) with usable output — use it.
+ *  - `running`: still in progress — the caller MUST defer (leave the marker, retry next tick), NOT
+ *    create a second billed session.
+ *  - `unavailable`: gone / terminated / ended without usable output — the caller runs fresh.
+ */
+type HarvestResult = {
+    state: "completed";
+    output: string;
+} | {
+    state: "running";
+} | {
+    state: "unavailable";
+};
+/**
+ * Crash-resume harvest: given a previously-created session id, decide whether it already produced
+ * usable output, is still running, or is unavailable — WITHOUT creating a new session or sending a
+ * new (billed) turn. Distinguishing `running` matters: returning "no result" for a still-running
+ * session would make the caller fork a second billed session (the timeout window can equal the cron
+ * re-claim window). Only an `idle` session that ended with `stop_reason=end_turn` and non-empty
+ * output counts as completed.
+ */
+declare function harvestAgentSession(sessionId: string): Promise<HarvestResult>;
+/** The values the agent produced for the step's declared slots. */
+type GeneratedSlots = Record<string, string>;
+/** Inputs to {@link generateSlots}. */
+interface GenerateSlotsInput {
+    agentId: string;
+    environmentId: string;
+    /** The slot names the step declares the agent must fill (R12/R14). */
+    aiSlots: readonly string[];
+    /** The per-step personalization brief (R12). */
+    brief: string;
+    /** The contact's raw host `data` — only allow-listed fields reach the agent (R44). */
+    contactData: Record<string, unknown>;
+    /** Host-declared allow-list of `data` fields the agent may see (R44). Empty ⇒ none. */
+    aiFieldAllowList: readonly string[];
+}
+/**
+ * Reduce arbitrary contact `data` to the allow-listed, value-clamped subset safe to send to the
+ * agent (R44). The recipient email is never included unless the host explicitly allow-lists it. Any
+ * field not on the list is dropped. Mirrors `lib/agent-sanitize.ts`, but driven by host config
+ * rather than a hardcoded list.
+ */
+declare function sanitizeContactForAgent(data: Record<string, unknown>, allowList: readonly string[]): Record<string, unknown>;
+/** Build the structured goal message the agent receives. The contact data is explicitly framed as
+ * untrusted data, not instructions (prompt-injection defense-in-depth). */
+declare function buildSlotGoal(input: GenerateSlotsInput): string;
+/**
+ * Content-seek the declared slot values out of the agent output. Returns `null` when the output is
+ * not a JSON object or is missing any declared slot — the caller treats `null` as a generation
+ * failure (leave the step due, never send empty/partial). Extra keys are ignored; non-string slot
+ * values are coerced to strings.
+ */
+declare function extractSlots(output: string, aiSlots: readonly string[]): GeneratedSlots | null;
+/**
+ * Generate (or harvest) the declared slots for a drip step. When `resumeSessionId` is set this is a
+ * re-claimed step: harvest the prior session and DEFER on `running` (never fork a second billed
+ * session). Otherwise run a fresh session, persisting the marker first.
+ *
+ * Returns a discriminated result so the engine can react without exceptions for the deferral path:
+ *  - `generated`: slots filled (fresh session); carries the new `sessionId` (already persisted).
+ *  - `harvested`: slots filled from a prior `completed` session — no new bill, no resend.
+ *  - `deferred`: a prior session is still `running` — leave the step due, retry next tick.
+ *  - `failed`: generation produced no usable slots, or the session errored. Leave the step due.
+ */
+type SlotGenerationResult = {
+    kind: "generated";
+    slots: GeneratedSlots;
+    sessionId: string;
+} | {
+    kind: "harvested";
+    slots: GeneratedSlots;
+} | {
+    kind: "deferred";
+} | {
+    kind: "failed";
+    reason: string;
+};
+interface GenerateOrHarvestInput extends GenerateSlotsInput {
+    /** A non-null inflight marker means re-claim — harvest the prior session instead of forking. */
+    resumeSessionId?: string | null;
+    /** Persist the new session id as the inflight marker BEFORE the billed turn (fresh path only). */
+    onSessionCreated?: (sessionId: string) => void | Promise<void>;
+    /** Per-call timeout override. */
+    timeoutMs?: number;
+}
+declare function generateOrHarvestSlots(input: GenerateOrHarvestInput): Promise<SlotGenerationResult>;
+
+/** Default ceiling on `broadcasts.list` pages walked during a crash-resume precheck. A real host
+ * persists the id on the common path, so the precheck only runs after a crash in the narrow
+ * persist gap; this budget bounds the cost AND is the fail-loud tripwire that prevents a
+ * blind re-create at high volume. */
+declare const DEFAULT_PRECHECK_MAX_PAGES = 20;
+/** Per-page size for the `broadcasts.list` precheck (Resend allows 1–100; default 20). */
+declare const DEFAULT_PRECHECK_PAGE_SIZE = 100;
+/** Default number of extra precheck attempts after an empty/no-match first pass, to absorb
+ * read-replica lag between `broadcasts.create` accepting and the new broadcast becoming
+ * listable. Each retry waits `retryDelayMs`. */
+declare const DEFAULT_PRECHECK_RETRIES = 2;
+/** Default delay (ms) between precheck retries. Small — replication lag, not a backoff. */
+declare const DEFAULT_PRECHECK_RETRY_DELAY_MS = 250;
+/**
+ * A broadcast claim row as stored. Times are ISO strings (Postgres TIMESTAMPTZ); the bare
+ * `broadcast_key` is the host key (namespace stripping is the caller's concern via the db wrapper).
+ */
+interface BroadcastClaimRow {
+    /** Host-supplied broadcast key (bare; one per broadcast issue). */
+    broadcastKey: string;
+    /** The Resend broadcast id, once `broadcasts.create` returned and it was persisted. Null in the
+     *  crash gap between accept and persist. */
+    resendBroadcastId: string | null;
+    /** Host content item ids included in this issue (provenance / cursor advance). */
+    itemIds: string[];
+    /** When the broadcast was marked sent. Null ⇒ unsent ⇒ resumable. */
+    sentAt: string | null;
+    /** When the claim row was created (the `broadcasts.list` precheck lower bound). */
+    createdAt: string;
+}
+/** Outcome of {@link claim}. */
+interface ClaimResult {
+    /** True when THIS caller won a fresh claim (the INSERT landed a row). Only a winner may send. */
+    won: boolean;
+    /** True when the (pre-existing) claim is a resumable prior attempt — `won === false` and the
+     *  existing row has `sent_at IS NULL`. A loser that is not resumable already sent (sent_at set)
+     *  and must do nothing. */
+    resumable: boolean;
+    /** The claim row (the freshly-inserted one on a win, the pre-existing one on a loss). Always
+     *  present after a claim — the INSERT … RETURNING wins return the new row; a loss reads the row
+     *  back (it must exist: the conflict implies a row). */
+    row: BroadcastClaimRow;
+}
+/**
+ * Atomically claim the right to send the broadcast for `broadcastKey`.
+ *
+ * `INSERT … ON CONFLICT DO NOTHING RETURNING` against `sdk_broadcast_claims`:
+ *   - WON (1 returned row): `{ won: true, resumable: false, row }`. The caller proceeds to render
+ *     + `broadcasts.create`, then calls {@link persistBroadcastId} and {@link markSent}.
+ *   - LOST (0 returned rows): a row already exists. We read it back to classify:
+ *       - `sent_at IS NULL`  → `{ won: false, resumable: true, row }`  (a crashed prior attempt — the
+ *          caller may resume via {@link resolveResumeBroadcastId}).
+ *       - `sent_at` set      → `{ won: false, resumable: false, row }` (already sent — do nothing).
+ *
+ * Success is read from `rows.length` (the won/lost signal), never `rowCount`.
+ *
+ * @throws if a lost claim cannot be read back (a row MUST exist after a conflict — its absence is a
+ *   torn write or a namespace mismatch, a fail-loud condition, not a silent re-send).
+ */
+declare function claim(db: NamespacedDb, broadcastKey: string, opts?: {
+    itemIds?: ReadonlyArray<string>;
+}): Promise<ClaimResult>;
+/**
+ * Persist the Resend broadcast id into the claim row, immediately after `broadcasts.create`
+ * returns. This is what lets the COMMON resume path read the id directly and never scan Resend.
+ * Idempotent: re-persisting the same id is a no-op-shaped UPDATE. Returns the updated row.
+ *
+ * @throws if no claim row exists for the key (persisting an id without a held claim is a contract
+ *   violation — the caller must `claim()` first).
+ */
+declare function persistBroadcastId(db: NamespacedDb, broadcastKey: string, resendBroadcastId: string): Promise<BroadcastClaimRow>;
+/**
+ * Mark the broadcast sent: set `sent_at = NOW()` and record the included item ids. After this, a
+ * future claim for the same key is a non-resumable loss (`sent_at` set ⇒ do nothing). Idempotent on
+ * `sent_at` (a second call refreshes the timestamp but the claim is already terminal). Returns the
+ * updated row.
+ */
+declare function markSent(db: NamespacedDb, broadcastKey: string, opts?: {
+    itemIds?: ReadonlyArray<string>;
+}): Promise<BroadcastClaimRow>;
+/** Knobs for the crash-resume precheck. All have safe defaults; tests override them. */
+interface ResumePrecheckOptions {
+    /** Max `broadcasts.list` pages to walk before failing loud. Default {@link DEFAULT_PRECHECK_MAX_PAGES}. */
+    maxPages?: number;
+    /** Page size for `broadcasts.list`. Default {@link DEFAULT_PRECHECK_PAGE_SIZE}. */
+    pageSize?: number;
+    /** Extra attempts after a no-match pass (replication lag). Default {@link DEFAULT_PRECHECK_RETRIES}. */
+    retries?: number;
+    /** Delay (ms) between retries. Default {@link DEFAULT_PRECHECK_RETRY_DELAY_MS}. */
+    retryDelayMs?: number;
+    /** Injectable sleep (tests pass a no-op). Defaults to a real `setTimeout` promise. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** Outcome of {@link resolveResumeBroadcastId}. */
+type ResumeResolution = 
+/** The broadcast already exists in Resend (found by name+created_at). Resume reads it; do NOT
+ *  re-create. `id` is the existing Resend broadcast id (from the persisted row or the precheck). */
+{
+    status: "exists";
+    broadcastId: string;
+    source: "persisted" | "precheck";
+}
+/** No matching broadcast exists after a bounded, retried precheck — it is SAFE to (re-)create.
+ *  This is only returned when the precheck completed within budget and found nothing. */
+ | {
+    status: "absent";
+};
+/**
+ * Resolve, for a resumable (`sent_at IS NULL`) claim, whether the broadcast already exists in
+ * Resend — so the caller can resume rather than blind-re-create (the double-blast R30 forbids).
+ *
+ * COMMON PATH: the persisted `resend_broadcast_id` is present → `{ status: "exists", source:
+ * "persisted" }` with no Resend call at all.
+ *
+ * CRASH GAP: the id is absent (crash after `broadcasts.create` accepted, before persist) → precheck
+ * `broadcasts.list` for the deterministic `name === broadcastKey`. Since the list endpoint has no
+ * name filter and no `created_at` filter param, we page (cursor `after`) and filter client-side,
+ * stopping a page early once `created_at < claim.createdAt` (results are newest-first; older pages
+ * cannot contain our broadcast). We retry the whole walk a few times to absorb read-replica lag.
+ *   - A name+created_at match → `{ status: "exists", source: "precheck" }` (resume; never re-create).
+ *   - No match within budget   → `{ status: "absent" }` (safe to create).
+ *   - Budget (maxPages) exhausted on ANY attempt → THROW (fail loud — operator confirmation; never
+ *     blind-re-create at high volume).
+ *
+ * `name === broadcastKey` is the deterministic name the broadcast lane sets on `broadcasts.create`
+ * (U12). It carries no server-side uniqueness — the LIST match, not the name, is the dedup.
+ *
+ * @throws when the precheck cannot complete within `maxPages` (fail loud), or when Resend is
+ *   unset/disabled (a resumable id-absent claim cannot be resolved without listing — surfacing it
+ *   beats a blind re-create), or on a Resend list error.
+ */
+declare function resolveResumeBroadcastId(resend: ResendClientHandle, claimRow: Pick<BroadcastClaimRow, "broadcastKey" | "resendBroadcastId" | "createdAt">, opts?: ResumePrecheckOptions): Promise<ResumeResolution>;
+
+/**
+ * The cursor identity: a program (a `defineBroadcastProgram` key) and a subject (the unit the
+ * watermark advances over — often a single global "default" subject for a simple newsletter, or a
+ * per-locale / per-segment subject for a fan-out program). Both are bare host keys; the db wrapper
+ * namespaces them so two installs on one Postgres never collide (R38).
+ */
+interface CursorKey {
+    /** Host program key (bare; namespaced by the db wrapper on write/read). */
+    programKey: string;
+    /** Host subject key (bare; the watermark advances per subject). */
+    subjectKey: string;
+}
+/** The cursor state as surfaced to the host. */
+interface CursorState {
+    /** The high-water mark over the host's ordering column, or null when the program has never sent
+     *  for this subject (a never-seen key reads as null without writing a row). */
+    watermark: string | null;
+    /** Monotonic issue sequence — how many issues have been sent for this (program, subject). 0 for a
+     *  never-seen key. The host may use it to label issues; `advance` records the host-supplied next
+     *  value (it does not auto-increment, so the host stays the source of truth). */
+    issueSeq: number;
+    /** When the cursor last advanced (a real send). Null for a never-seen key. Exposed as a HEALTH
+     *  signal: a stale lastFiredAt means the host's cron may have stopped (R36). */
+    lastFiredAt: string | null;
+    /** Whether the host has paused this (program, subject). A paused cursor is never `due`. */
+    paused: boolean;
+}
+/**
+ * Read the cursor state for `key`. A never-seen key reads as the lazy default
+ * (`{ watermark: null, issueSeq: 0, lastFiredAt: null, paused: false }`) WITHOUT writing a row — a
+ * pure read has no side effects, so the cursor row is materialized only on the first `advance`.
+ */
+declare function read(db: NamespacedDb, key: CursorKey): Promise<CursorState>;
+/** Options for {@link due}. */
+interface DueOptions {
+    /** The cadence window in days — `due` is true once this many days have elapsed since the last
+     *  send. Must be a finite, positive number. */
+    cadenceDays: number;
+    /** Injectable clock (tests pass a fixed instant). Defaults to `Date.now()`. */
+    now?: () => number;
+}
+/**
+ * The N-day timer. Returns whether a send is DUE for the given cursor state and cadence:
+ *   - paused                     → false (a paused cursor never fires)
+ *   - never fired (lastFiredAt null) → true (the first issue is always due)
+ *   - lastFiredAt unparseable    → true (fail toward firing rather than silently stalling; a bad
+ *                                  stored timestamp should surface as a send, not an indefinite gap)
+ *   - otherwise                  → (now - lastFiredAt) >= cadenceDays
+ *
+ * `due` is a pure predicate over the passed state — it never reads the db. The caller pairs it with
+ * {@link read}.
+ *
+ * @throws on a non-finite or non-positive `cadenceDays` (a zero/negative cadence is a config bug:
+ *   it would fire every tick — fail loud rather than blast).
+ */
+declare function due(state: CursorState, opts: DueOptions): boolean;
+/** Options for {@link advance}. */
+interface AdvanceOptions {
+    /** The new high-water mark — the ordering-column value of the newest item included in THIS send.
+     *  Must be a non-null, non-empty string that is strictly greater than the stored watermark. A
+     *  null/empty value is rejected (R45: the host's nullable ordering-column mistake surfaces here). */
+    watermark: string;
+    /** The issue sequence this send represents (host-supplied; the host owns issue numbering). When
+     *  omitted, the stored `issue_seq` is incremented by 1. */
+    issueSeq?: number;
+    /** Provenance: the host content item ids included in this issue. Stored on the row for audit; not
+     *  part of the watermark compare. (Reserved for parity with the claim row; currently advisory.) */
+    itemIds?: ReadonlyArray<string>;
+    /** Injectable clock for `last_fired_at` in tests. Defaults to DB `NOW()` when omitted. */
+    firedAt?: string;
+}
+/** Outcome of {@link advance}. */
+interface AdvanceResult {
+    /** True iff the watermark actually moved (the strictly-greater compare passed and the row was
+     *  written). False only via {@link tryAdvance} when the incoming watermark was not greater (a
+     *  skip-zero / only-if-new tick). `advance` itself throws on a non-monotonic watermark rather than
+     *  returning `advanced: false`. */
+    advanced: boolean;
+    /** The cursor state after the operation (the new state on an advance; the unchanged stored state
+     *  on a no-op skip). */
+    state: CursorState;
+}
+/**
+ * Advance the cursor for `key` — called ONLY on a real send (R36). Writes the new watermark, issue
+ * sequence, and `last_fired_at` iff the incoming watermark is STRICTLY GREATER than the stored one.
+ *
+ * Rejects (throws), never silently advancing:
+ *   - a null / non-string / empty `watermark` (R45 — the nullable ordering-column mistake), and
+ *   - a non-monotonic `watermark` (<= the stored value: a same-instant duplicate or clock skew /
+ *     replay that would re-send already-sent content).
+ *
+ * The write is a single upsert (`INSERT … ON CONFLICT … DO UPDATE`) guarded in its `WHERE` by the
+ * strictly-greater compare, so two concurrent ticks racing the same key cannot both advance — the
+ * loser's UPDATE matches no row and it re-reads the (advanced) state. Materializes the row on first
+ * advance.
+ *
+ * For the skip-zero / only-if-new path (no new content ⇒ DO NOT advance), use {@link tryAdvance},
+ * which returns `{ advanced: false }` instead of throwing.
+ */
+declare function advance(db: NamespacedDb, key: CursorKey, opts: AdvanceOptions): Promise<CursorState>;
+/**
+ * The skip-tolerant sibling of {@link advance}. Identical watermark validation (a null/empty
+ * watermark still throws — that is a config bug, not a skip), but a NON-MONOTONIC watermark returns
+ * `{ advanced: false, state: <unchanged stored state> }` instead of throwing. Use this on the
+ * only-if-new / skip-zero path where "nothing newer to send" is an expected no-op, not an error.
+ */
+declare function tryAdvance(db: NamespacedDb, key: CursorKey, opts: AdvanceOptions, cfg?: {
+    rejectNonMonotonic?: boolean;
+}): Promise<AdvanceResult>;
+/**
+ * Set the paused flag for `key` (a host kill-switch independent of the watermark). Materializes the
+ * row if absent. A paused cursor is never {@link due}. Returns the post-update state.
+ */
+declare function setPaused(db: NamespacedDb, key: CursorKey, paused: boolean): Promise<CursorState>;
+
+/**
+ * A declared variable on a Resend Template. The SDK fills these in code for the broadcast lane.
+ * `key` is the bare variable name (the `{{key}}` slot), `fallback` is the Template's own default
+ * when the host supplies no value, `type` is Resend's declared scalar type.
+ */
+interface TemplateVariableSpec {
+    key: string;
+    fallback: string | number | null;
+    type: "string" | "number";
+}
+/**
+ * The fields of a fetched Resend Template the broadcast renderer needs: the raw `html`/`text`
+ * bodies (pre-substitution) and the declared variable specs. Everything else on the Resend
+ * `Template` (status, timestamps, versioning) is irrelevant to rendering and dropped.
+ */
+interface FetchedTemplate {
+    id: string;
+    html: string;
+    text: string | null;
+    variables: readonly TemplateVariableSpec[];
+}
+/** Raised when the Template cannot be fetched (Resend unset, not-found, or an upstream error). */
+declare class TemplateFetchError extends Error {
+    constructor(message: string);
+}
+/** Drop the cache (tests; or a host that knows a Template was edited upstream mid-process). */
+declare function clearTemplateCache(): void;
+/**
+ * Fetch a Resend Template by id and return its render-relevant fields, caching the result.
+ *
+ * - A cache hit returns immediately and does NOT call Resend (satisfies "second send does not
+ *   re-fetch"). Pass `{ refresh: true }` to force a re-fetch.
+ * - Resend unset (no key) is a hard error here, not a no-op: the broadcast lane cannot render
+ *   without the Template's bodies, so silently producing an empty broadcast would be a bug. This
+ *   mirrors `provisionTopic`, which also refuses to no-op when a real upstream id is required.
+ * - An upstream error or a missing Template (`data === null`) fails loud.
+ */
+declare function getTemplate(resend: ResendClientHandle, id: string, opts?: {
+    refresh?: boolean;
+}): Promise<FetchedTemplate>;
+
+/** Host-supplied values for the Template's declared variables. Scalars only (Resend's model). */
+type BroadcastVariables = Record<string, string | number | boolean | null | undefined>;
+/** Raised when render or dispatch cannot proceed. Carries a stable, named contract message. */
+declare class BroadcastRenderError extends Error {
+    constructor(message: string);
+}
+interface RenderBroadcastInput {
+    /** Saved Resend Template id to render from. */
+    templateId: string;
+    /** Values for the Template's declared `{{key}}` variables. Missing keys use the Template fallback. */
+    variables?: BroadcastVariables;
+}
+interface RenderedBroadcast {
+    templateId: string;
+    /** `html` body with declared variables filled and merge tags left verbatim. */
+    html: string;
+    /** `text` body, same substitution rules. `null` when the Template has no text part. */
+    text: string | null;
+}
+/**
+ * Fetch the (cached) Resend Template and fill its declared variables in code, preserving merge
+ * tags verbatim. Returns broadcast-ready `{ html, text }`. Does NOT call `broadcasts.create` —
+ * `sendBroadcast` composes this with dispatch; expose the pure render for hosts that want it.
+ */
+declare function renderBroadcast(resend: ResendClientHandle, input: RenderBroadcastInput): Promise<RenderedBroadcast>;
+interface SendBroadcastInput extends RenderBroadcastInput {
+    /** Target Resend Segment (canonical broadcast target; `audienceId` is deprecated, R17). */
+    segmentId: string;
+    /** Topic to scope delivery + consent to (the unsubscribe gate, KTD9). */
+    topicId: string;
+    /** Verified sender address. */
+    from: string;
+    subject: string;
+    /** Broadcast name — the SDK passes the send-once `broadcastKey` here so listings can find it (U11). */
+    name?: string;
+    replyTo?: string | string[];
+    previewText?: string;
+    /**
+     * Dispatch immediately (`send: true`, the default) vs create-only. When `scheduledAt` is set,
+     * Resend schedules instead of sending now.
+     */
+    send?: boolean;
+    /** ISO timestamp (or Resend natural-language) to schedule the broadcast instead of sending now. */
+    scheduledAt?: string;
+}
+interface SendBroadcastResult {
+    /** The Resend broadcast id returned by `broadcasts.create`. */
+    broadcastId: string;
+    html: string;
+    text: string | null;
+}
+/**
+ * Render a Resend Template and dispatch it as a Broadcast in a single call (origin R31/R32):
+ * `templates.get` → fill in code → `broadcasts.create({ segmentId, topicId, html, text, send })`.
+ *
+ * No `templateId` and no headers are passed to `broadcasts.create` — broadcasts accept neither
+ * (verified against resend@6.14.0). The Topic id carries the unsubscribe gate; the rendered html
+ * still contains `{{{RESEND_UNSUBSCRIBE_URL}}}` for Resend to resolve per-contact.
+ *
+ * Fails loud when Resend is unset (rendering already requires the Template) or when
+ * `broadcasts.create` errors — a broadcast that silently did not dispatch would be a compliance bug.
+ */
+declare function sendBroadcast(resend: ResendClientHandle, input: SendBroadcastInput): Promise<SendBroadcastResult>;
+
+/**
+ * One resolved topic-cache entry: the host-meaningful `(stream, subject)` for a Resend topic id.
+ * `topicKey` is the canonical `stream:subject` string the consent mirror stores on `topic_key`.
+ */
+interface ResolvedTopic {
+    topicId: string;
+    topicKey: string;
+    stream: Stream;
+    subject: string;
+}
+/** Why a single reconcile ended the way it did. */
+type ReconcileOutcome = 
+/** The diff + segment repair completed; the contact row was cleared dirty. */
+"reconciled"
+/** Resend is unset (no key) — nothing to diff; the contact stays dirty for a later run. */
+ | "skipped"
+/** A 429 was hit; the caller backed off. The contact stays dirty (retried next tick). */
+ | "rate_limited"
+/** A `topics.list` entry id was absent from the provisioning cache — fail loud. The contact stays
+ *  dirty and is SURFACED (never silently ignored — an unmapped opt_out is a consent leak). */
+ | "unmapped"
+/** A non-rate-limit Resend error occurred; the contact stays dirty (retried). */
+ | "error";
+/** Result of {@link reconcileContact}. Carries the observable changes (no PII beyond the email the
+ * caller already holds) so a sweep can summarize what it repaired. */
+interface ReconcileContactResult {
+    email: string;
+    outcome: ReconcileOutcome;
+    /** Topic keys whose mirror state reconcile flipped to `opt_out` (drift caught from Resend). */
+    optedOut: string[];
+    /** True when the base-Segment membership was (re-)asserted for this contact. */
+    segmentRepaired: boolean;
+    /** Topic ids on the contact in Resend that the provisioning cache could not map — the fail-loud
+     *  signal. Non-empty ⇒ `outcome === "unmapped"`. */
+    unmappedTopicIds: string[];
+}
+/** Inputs to {@link reconcileContact}. */
+interface ReconcileContactInput {
+    email: string;
+    /** Pre-loaded `topicId → (stream, subject)` map (built once per sweep via {@link loadTopicCache}).
+     *  Pass it in to avoid re-querying the cache per contact. */
+    topicCache: Map<string, ResolvedTopic>;
+    /** Backoff before resume on a 429 (ms). Defaults to {@link DEFAULT_BACKOFF_MS}. Tests pass 0. */
+    backoffMs?: number;
+    /** Injectable sleep (tests stub it). Defaults to a real timer. */
+    sleepFn?: (ms: number) => Promise<void>;
+}
+/**
+ * Reconcile ONE contact: diff `contacts.topics.list` against the mirror and repair base-Segment
+ * membership. The load-bearing steps, in order:
+ *
+ *   1. List the contact's topics from Resend (`contacts.topics.list`). A 429 here backs off and
+ *      returns `rate_limited` WITHOUT clearing dirty (the next tick retries). A non-429 error
+ *      returns `error`, also leaving dirty.
+ *   2. For every listed topic, map its `id` to `(stream, subject)` via the provisioning cache. An
+ *      id ABSENT from the cache is fail-loud: it is collected into `unmappedTopicIds`, the contact
+ *      stays dirty, and the outcome is `unmapped` — we NEVER silently ignore it (a topic Resend
+ *      reports opted-out that we cannot map is a consent leak we must surface).
+ *   3. For every MAPPED topic Resend reports `opt_out`, write `opt_out` into the mirror (monotonic —
+ *      `consent.set`-equivalent merge in SQL only moves toward MORE suppression).
+ *   4. Repair base-Segment membership: re-assert the contact in the base Segment (idempotent add) so
+ *      an opted-in contact missing from the Segment still receives the issue (intersection target).
+ *   5. On a clean pass (no unmapped ids, no rate-limit/error), CLEAR the contact's dirty flag.
+ *
+ * Never throws on a Resend hiccup — every failure is folded into the typed outcome (fail-soft),
+ * EXCEPT a hard DB write failure, which propagates (a mirror we cannot write is a contract
+ * violation, not an external-service blip).
+ */
+declare function reconcileContact(envoy: Envoy, input: ReconcileContactInput): Promise<ReconcileContactResult>;
+/** Options for {@link reconcile}. */
+interface ReconcileOptions {
+    /**
+     * Sweep mode:
+     *   - `"dirty"` (default): visit only contacts with `dirty_since IS NOT NULL` (the cheap,
+     *     narrowed per-tick sweep). Bounded by `maxContacts`.
+     *   - `"full"`: visit EVERY contact, resuming from the persisted full-sweep cursor; advances the
+     *     cursor as it goes so a later tick continues where this one stopped.
+     */
+    mode?: "dirty" | "full";
+    /** Max contacts to process this tick (the per-tick budget / fan-out window). Default 200. */
+    maxContacts?: number;
+    /** Backoff before resume on a 429 (ms). Default {@link DEFAULT_BACKOFF_MS}. Tests pass 0. */
+    backoffMs?: number;
+    /** Injectable sleep (tests stub it). */
+    sleepFn?: (ms: number) => Promise<void>;
+}
+/** Result of a {@link reconcile} sweep. */
+interface ReconcileSweepResult {
+    mode: "dirty" | "full";
+    /** Contacts visited this tick. */
+    processed: number;
+    /** Contacts whose diff landed clean (dirty cleared). */
+    reconciled: number;
+    /** Contacts whose Resend topic ids could not all be mapped (fail-loud; surfaced, still dirty). */
+    unmapped: ReconcileContactResult[];
+    /** True when a 429 paused the sweep mid-tick (it will resume next tick). */
+    rateLimited: boolean;
+    /** For a full sweep: the cursor (last contact id processed) to resume from next tick; null when
+     *  the full sweep reached the end and the cursor was reset. Undefined for a dirty sweep. */
+    resumeCursor?: string | null;
+}
+/**
+ * The reconcile sweep — the broadcast lane's pre-send consistency pass (R29). Runs as the LAST step
+ * before `broadcasts.create` (see U15's `runIssue` ordering). Two modes:
+ *
+ *   - DIRTY (default): processes the dirty-set (`sdk_contacts.dirty_since IS NOT NULL`) up to the
+ *     per-tick budget. This is the cheap, narrowed path the broadcast loop calls each issue.
+ *   - FULL: a periodic safety net that walks EVERY contact, resumable across ticks via a persisted
+ *     cursor (`sdk_program_state` under `__envoy_reconcile_sweep__`). A tick that exhausts its
+ *     budget persists the last id; the next FULL tick resumes after it. When the walk reaches the
+ *     end, the cursor resets to null (the next full sweep starts over).
+ *
+ * Per-contact fail-soft: one contact's Resend error never aborts the sweep — it leaves that contact
+ * dirty and moves on. A 429 pauses the sweep for the rest of THIS tick (so we don't hammer a
+ * rate-limited account) and resumes next tick; the paused contact stays dirty.
+ */
+declare function reconcile(envoy: Envoy, options?: ReconcileOptions): Promise<ReconcileSweepResult>;
+
+/** Raised when a program DEFINITION is malformed (fail loud at definition time, mirroring
+ *  {@link SequenceDefinitionError} in the drip lane). A bad `render`, a non-positive cadence, or a
+ *  missing segment is a config bug surfaced at `defineBroadcastProgram` time, not at first send. */
+declare class BroadcastProgramError extends Error {
+    constructor(message: string);
+}
+/** A `(stream, subject)` topic identity for a program subject — the unit a recipient leaves on
+ *  Resend's hosted preference page (R27). `topicKeyFor(subjectKey)` returns this so a program over
+ *  per-locale subjects (`"IT"`, `"FR"`) provisions one Topic per subject. */
+interface ProgramTopic {
+    stream: Stream;
+    subject: string;
+}
+/**
+ * The context handed to a program's `render` for one issue of one subject. The host's `render` owns
+ * the CONTENT decision (what Template, what variables, what subject line) given the items it was
+ * passed and the cursor position; the SDK owns the mechanics around it.
+ */
+interface RenderContext {
+    /** The subject this issue is for (bare host key; e.g. `"default"`, `"IT"`). */
+    subjectKey: string;
+    /** The host content items the host decided are NEW for this issue (the host owns the content query
+     *  — R35). May be empty; a `render` that returns `null` for an empty batch is the skip path. */
+    items: ReadonlyArray<unknown>;
+    /** The cursor state read just before render — `{ watermark, issueSeq, lastFiredAt, paused }`. The
+     *  `render` reads `issueSeq` to label the issue and `watermark` to know the prior high-water mark. */
+    cursor: CursorState;
+    /** The provisioned Resend Topic id for this subject (the unsubscribe gate, KTD9). */
+    topicId: string;
+}
+/**
+ * What a program's `render` returns for one issue. Mirrors {@link SendBroadcastInput} minus the
+ * mechanics the SDK fills in (`segmentId`, `topicId`, `name` are supplied by `runIssue`), PLUS the
+ * `advance` payload (`watermark`/`issueSeq`/`itemIds`) so the host names the new high-water mark for
+ * the SAME issue it rendered. Returning `null`/`undefined` is the explicit SKIP signal (nothing new
+ * to send) — `runIssue` then neither sends nor advances.
+ */
+interface RenderedIssue {
+    /** Saved Resend Template id to render this issue from. */
+    templateId: string;
+    /** Values for the Template's declared `{{key}}` variables (merge tags stay verbatim). */
+    variables?: BroadcastVariables;
+    /** Sender address. Falls back to the program's `from`, then the SDK has no default (it throws). */
+    from?: string;
+    /** Subject line for this issue. */
+    subject: string;
+    replyTo?: string | string[];
+    previewText?: string;
+    /** Schedule instead of sending now (Resend ISO/natural-language). */
+    scheduledAt?: string;
+    /**
+     * The new high-water mark for THIS issue — the ordering-column value of the newest item included.
+     * Advanced ONLY after the send is accepted, strictly-greater (R36). A null/empty value is a host
+     * contract bug (a nullable ordering column) and is rejected by `cursor.advance` (R45).
+     */
+    watermark: string;
+    /** Issue sequence to record (host owns numbering). Defaults to `cursor.issueSeq + 1`. */
+    issueSeq?: number;
+    /** Content item ids included (provenance, recorded on the claim + cursor rows). */
+    itemIds?: ReadonlyArray<string>;
+}
+/** A program's `render` callback. Async-allowed. Returns a {@link RenderedIssue}, or `null`/
+ *  `undefined` to SKIP (no new content → no send, no advance). */
+type ProgramRender = (ctx: RenderContext) => RenderedIssue | null | undefined | Promise<RenderedIssue | null | undefined>;
+/** Inputs to {@link defineBroadcastProgram}. */
+interface DefineBroadcastProgramInput {
+    /** Stable program key (the cursor + claim rows are scoped to it; namespaced by the db wrapper). */
+    key: string;
+    /** Target Resend Segment id (the canonical broadcast target; intersected with the Topic). */
+    segmentId: string;
+    /** Map a subject key to its `(stream, subject)` Topic identity. Defaults to `{ stream: "digest",
+     *  subject: subjectKey }` — a single-stream newsletter. */
+    topicKeyFor?: (subjectKey: string) => ProgramTopic;
+    /** The N-day cadence for `due` (R36). Must be finite and positive. */
+    cadenceDays: number;
+    /** Default sender address used when a `render` omits `from`. */
+    from?: string;
+    /** The host content/subject renderer (see {@link ProgramRender}). */
+    render: ProgramRender;
+}
+/** Why a {@link runIssue} call did NOT send (a non-error, expected no-op). */
+type IssueSkipReason = 
+/** The cadence window has not elapsed since the last send (and the caller did not `force`). */
+"not_due"
+/** This (program, subject) cursor is paused (a host kill-switch). */
+ | "paused"
+/** `render` returned `null`/`undefined` — the host had nothing new to send. */
+ | "empty"
+/** The claim was lost to a concurrent tick that already sent (send-once: this caller does NOT
+ *  re-send). The other tick owns this issue. */
+ | "claim_lost"
+/** The claim was already marked sent (a duplicate trigger after a completed issue). */
+ | "already_sent";
+/** The outcome of one {@link runIssue} call. Exactly one of `sent` / `skipped` / `failed` is the
+ *  dominant state; `failed` is the per-subject fail-soft capture (the host loop continues). */
+interface RunIssueResult {
+    /** The bare program key. */
+    programKey: string;
+    /** The bare subject key this issue was for. */
+    subjectKey: string;
+    /** The broadcast key (`programKey:subjectKey:issueSeq`) used as the claim id + Resend broadcast
+     *  name. Present whenever a claim was attempted. */
+    broadcastKey?: string;
+    /** True iff a broadcast was accepted by Resend this call (`broadcasts.create` returned an id) OR a
+     *  resumable prior attempt was resolved as already-existing and finalized. */
+    sent: boolean;
+    /** The Resend broadcast id, when `sent`. */
+    broadcastId?: string;
+    /** Set when the call was a deliberate no-op (not an error). */
+    skipped?: IssueSkipReason;
+    /** Set when a fail-soft error was captured (a Resend hiccup on THIS subject). The host loop must
+     *  continue to the next subject; this subject retries next tick. The message is redacted (R43). */
+    failed?: string;
+    /** The reconcile sweep summary run before the send (present whenever reconcile ran). */
+    reconcile?: ReconcileSweepResult;
+    /** The cursor state after the call (advanced on a send; unchanged on a skip/fail). */
+    cursor?: CursorState;
+}
+/**
+ * A defined broadcast program — the declarative handle. Exposes:
+ *   - the program's static config (`key`, `segmentId`, `cadenceDays`, …) for introspection (U16 MCP),
+ *   - `runIssue(envoy, { subjectKey, items })`: the bundled, per-subject fail-soft ordering, and
+ *   - the RAW primitives bound to this program's keys (`reconcile`, `claim`, `render`/`send`,
+ *     `cursor.read/due/advance`) for hosts that need a custom ordering. The raw module-level
+ *     primitives stay exported from the package root too (this is sugar, not a replacement).
+ */
+interface BroadcastProgram {
+    readonly key: string;
+    readonly segmentId: string;
+    readonly cadenceDays: number;
+    readonly from?: string;
+    /** Resolve a subject's `(stream, subject)` Topic identity. */
+    topicFor(subjectKey: string): ProgramTopic;
+    /** The cursor key for a subject (`{ programKey: key, subjectKey }`). */
+    cursorKey(subjectKey: string): {
+        programKey: string;
+        subjectKey: string;
+    };
+    /** The deterministic broadcast key for a subject + issue sequence (`key:subjectKey:issueSeq`). */
+    broadcastKey(subjectKey: string, issueSeq: number): string;
+    /** Run ONE issue for ONE subject with the canonical ordering (per-subject fail-soft). */
+    runIssue(envoy: Envoy, input: RunIssueInput): Promise<RunIssueResult>;
+}
+/** Inputs to {@link BroadcastProgram.runIssue}. */
+interface RunIssueInput {
+    /** The subject to run (defaults to `"default"` — a single-subject newsletter). */
+    subjectKey?: string;
+    /** The host content items the host decided are new for this issue (handed to `render`). */
+    items?: ReadonlyArray<unknown>;
+    /** Bypass the cadence `due` check (a host-forced manual issue). The send-once claim still guards
+     *  against a double-send — `force` only skips the timer, never the claim. */
+    force?: boolean;
+    /** Override the reconcile sweep options for this issue (mode, budget, backoff). */
+    reconcile?: ReconcileOptions;
+    /** Override the crash-resume precheck knobs (max pages, retries) for this issue. */
+    resume?: ResumePrecheckOptions;
+    /** Injectable clock for the `due` check (tests). */
+    now?: () => number;
+}
+/**
+ * Define a broadcast program (R35). Validates loud at definition time: a missing/empty `key` or
+ * `segmentId`, a non-positive `cadenceDays`, or a non-function `render` throws
+ * {@link BroadcastProgramError}. Returns a frozen {@link BroadcastProgram} handle.
+ *
+ * The handle is pure config + bound methods — it touches no network or DB at definition time (so a
+ * module that defines programs at import has no Resend/DB dependency, preserving the unset-key no-op).
+ */
+declare function defineBroadcastProgram(input: DefineBroadcastProgramInput): BroadcastProgram;
+
+/** Resolve a {@link Sequence} by key — a `Map` of `key → Sequence`, or a lookup function. Mirrors
+ *  the drip cron's `SequenceRegistry` so the same host registration drives both surfaces. */
+type McpSequenceRegistry = ReadonlyMap<string, Sequence> | ((key: string) => Sequence | undefined);
+/** Resolve a {@link BroadcastProgram} by key — a `Map`, or a lookup function. */
+type McpProgramRegistry = ReadonlyMap<string, BroadcastProgram> | ((key: string) => BroadcastProgram | undefined);
+/**
+ * Verify an MCP bearer token, returning an {@link AuthInfo} when valid or `undefined` to reject.
+ * The default ({@link defaultVerifyMcpToken}) is a constant-time compare against the configured
+ * `mcpSecret`; a host that wants its `authorize(req)` to recognize an agent token can inject its own.
+ */
+type McpVerifyToken = (request: Request, bearerToken: string | undefined) => AuthInfo | undefined | Promise<AuthInfo | undefined>;
+/** Config for {@link createMcpRouteHandler}. */
+interface McpRouteConfig {
+    /** The root SDK handle (DB, Resend, agent, redaction). */
+    envoy: Envoy;
+    /**
+     * The dedicated MCP credential (R42). Used by the default token verifier. The route factory (U4)
+     * also gates `/mcp` against this; this module re-checks it so a standalone mount is never open.
+     * When omitted (and no custom `verifyToken`), the MCP handler fails closed (every call rejected).
+     */
+    mcpSecret?: string;
+    /** Custom token verifier (overrides the default constant-time `mcpSecret` compare). */
+    verifyToken?: McpVerifyToken;
+    /** Sequences an agent may enroll into / inspect (host `defineSequence` definitions). */
+    sequences?: McpSequenceRegistry;
+    /** Broadcast programs an agent may trigger / inspect (host `defineBroadcastProgram` handles). */
+    programs?: McpProgramRegistry;
+    /** Absolute https landing URL the drip List-Unsubscribe header points at — passed through for
+     *  parity with the engine config; unused by the current read/enroll tools. */
+    unsubscribeBaseUrl?: string;
+    /** Max MCP request duration (seconds). Mirrors the app's `{ maxDuration: 60 }`. */
+    maxDuration?: number;
+}
+/**
+ * The default MCP token verifier: a constant-time compare of the bearer token against `mcpSecret`.
+ * Returns an {@link AuthInfo} on a match, `undefined` otherwise. An unset/empty `mcpSecret` or a
+ * missing bearer token always rejects (never open, R42).
+ */
+declare function defaultVerifyMcpToken(mcpSecret: string | undefined): McpVerifyToken;
+/**
+ * Register the single-tenant lifecycle tools on an {@link McpServer}. Exposed standalone (in addition
+ * to being wired by {@link createMcpRouteHandler}) so a host that builds its own MCP server can reuse
+ * the exact tool set, and so tests can register against an in-memory server.
+ *
+ * Every tool that WRITES goes through the same server fn the host calls directly, so the suppression
+ * mirror, the send-once claim, and the per-topic consent gate all apply unchanged.
+ */
+declare function registerEnvoyTools(server: McpServer, config: McpRouteConfig): void;
+/** Instructions surfaced to the connecting agent (the app's `SERVER_INSTRUCTIONS`, single-tenant). */
+declare const SERVER_INSTRUCTIONS: string;
+/**
+ * Build the `/mcp` {@link SubHandler}. Constructs the MCP server with `createMcpHandler`, registers
+ * the single-tenant lifecycle tools, and wraps it with `withMcpAuth({ required: true })` so the MCP
+ * server itself is never open (R42) — independent of the route factory's outer `mcpSecret` gate.
+ *
+ * Returns a Web-standard `(Request) => Promise<Response>`, so it slots directly into
+ * `createEnvoyHandler({ ..., mcp })` and stays App-Router compatible.
+ */
+declare function createMcpRouteHandler(config: McpRouteConfig): SubHandler;
+
+/**
+ * Raised when a host-contract validation fails loud at config time (R45). Carries no secret values;
+ * the message names the offending field/slot/column and what to fix. Distinct from
+ * `SequenceDefinitionError` (shape) and `cursor.advance`'s runtime guard (the last-line defense): a
+ * `ValidationError` is the EARLY, actionable surfacing of the same class of mistake.
+ */
+declare class ValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Assert a transactional send names a valid `stream` (R45/R46). A transactional email's
+ * `List-Unsubscribe` token is stream-scoped (R33), so a send with no stream cannot carry a working
+ * one-click opt-out — it must be rejected at CONFIG time, never sent malformed.
+ *
+ * Callable wherever a stream is first declared (a host can run it at wiring to fail before any send).
+ * `drip/transactional.ts` also re-checks at call time; this is the early surfacing of the same rule.
+ *
+ * @throws {ValidationError} on a missing / non-string / unknown stream.
+ */
+declare function assertTransactionalStream(stream: unknown, context?: string): asserts stream is Stream;
+/**
+ * The host's declaration of the ordering column that backs a broadcast program's monotonic cursor.
+ * The SDK cannot read the host's content tables (R38/R45), so the host DECLARES the column it
+ * advances the watermark over, and the SDK validates the declaration is sound at setup.
+ */
+interface WatermarkColumnDeclaration {
+    /** The host column name backing the watermark (e.g. `created_at`, `id`). Informational + surfaced
+     *  in error messages; must be non-empty. */
+    column: string;
+    /** The column's scalar type — a timestamp/id ordering column. Both sort monotonically (timestamps
+     *  lexicographically as ISO-8601, ids numerically) — matching `cursor.advance`'s compare. */
+    type: "timestamptz" | "timestamp" | "bigint" | "integer" | "text" | "uuid";
+    /** Whether the host column is NULLABLE. MUST be `false`: a nullable ordering column cannot back a
+     *  strictly-greater watermark (a null row has no position), so a `true` here is rejected at setup
+     *  rather than surfacing as a `cursor.advance` throw on the first real send (R36/R45). */
+    nullable: boolean;
+}
+/**
+ * Assert a broadcast program's declared watermark column is non-nullable (R45). A nullable ordering
+ * column cannot back the monotonic cursor: `cursor.advance` rejects a null watermark at runtime, but
+ * that is the LAST-line defense (it would fail at the first send). This is the EARLY surfacing — a
+ * host that declares `nullable: true` at `defineBroadcastProgram` setup fails immediately, before any
+ * cron is wired.
+ *
+ * @throws {ValidationError} on a `nullable: true` declaration, an empty column, or an unknown type.
+ */
+declare function assertWatermarkColumnType(decl: WatermarkColumnDeclaration, context?: string): void;
+/**
+ * The outcome of validating ONE sequence step's `aiSlots` against its Template. Exactly one of
+ * `ok` / `warned` / `missing` is the dominant state per step:
+ *   - `ok: true`        — every declared slot exists on the Template's concrete variable list.
+ *   - `warned`          — the Template returned `variables: null` (a draft / variable-less Template):
+ *                         we CANNOT CONFIRM the slots, so this is a warning, not a failure.
+ *   - `missing` (≥ 1)   — the Template has a concrete variable list and one or more declared slots are
+ *                         absent from it: a hard error (collected, then thrown together).
+ */
+interface StepSlotCheck {
+    stepIndex: number;
+    templateId: string;
+    /** Declared slots that do NOT exist on the Template's concrete variable list. */
+    missing: readonly string[];
+    /** True when the Template's variables came back `null` (cannot confirm — a warning). */
+    warned: boolean;
+}
+/** The full result of {@link validateSequenceSlots} — a per-step breakdown plus rolled-up warnings. */
+interface SequenceValidationResult {
+    sequenceKey: string;
+    steps: readonly StepSlotCheck[];
+    /** Human-readable warnings (one per draft/variable-less Template a slot could not be confirmed
+     *  against). Surfaced to the host (R39) — never swallowed, never fatal. */
+    warnings: readonly string[];
+}
+/** Drop the slot-check cache (tests; or a host that knows a Template was edited upstream). */
+declare function clearValidationCache(): void;
+/**
+ * Validate ONE sequence's declared `aiSlots` against its steps' Resend Templates (the lazy, network
+ * arm of R45). Fetches each step's Template (cached, deduped), then for each step:
+ *   - concrete variable list present  → every declared slot must exist on it, else `missing`.
+ *   - `variables: null` (draft)       → cannot confirm → `warned: true`, surfaced as a warning.
+ *
+ * Collects ALL missing slots across ALL steps and throws ONE `ValidationError` listing every offender
+ * (so a host fixes them in a single pass, not one error per redeploy). When nothing is missing it
+ * returns the per-step breakdown plus any warnings (never throws on a warning).
+ *
+ * @throws {ValidationError} when one or more declared slots are absent from a concrete Template list,
+ *   or when a Template cannot be fetched (Resend unset / not found / upstream error).
+ */
+declare function validateSequenceSlots(resend: ResendClientHandle, sequence: Sequence, opts?: {
+    refresh?: boolean;
+}): Promise<SequenceValidationResult>;
+/**
+ * Validate MANY sequences in one pass (the shape `envoy.validate()` drives). Runs each sequence's
+ * slot check (sharing the per-Template cache so a Template referenced by two sequences is fetched
+ * once), accumulates warnings, and throws on the FIRST sequence that has missing slots (its
+ * `ValidationError` already lists every offender within that sequence).
+ *
+ * Returns the aggregate result (all per-sequence breakdowns + all warnings) when every sequence is OK
+ * or only warns. This is the function a host calls explicitly at deploy time; it is also what the
+ * drip engine can call lazily on a sequence's first tick (cached, so subsequent ticks are free).
+ */
+declare function validateSequences(resend: ResendClientHandle, sequences: readonly Sequence[], opts?: {
+    refresh?: boolean;
+}): Promise<{
+    sequences: readonly SequenceValidationResult[];
+    warnings: readonly string[];
+}>;
+/** Inputs to {@link validateConfig} / `envoy.validate()`. */
+interface ValidateInput {
+    /** Sequences whose declared `aiSlots` are checked against their Templates (the network arm). */
+    sequences?: readonly Sequence[];
+    /** Per-program watermark column declarations checked for non-nullability (the sync arm). */
+    watermarks?: readonly WatermarkColumnDeclaration[];
+    /** Force a re-fetch of every Template (ignore the slot-check cache). */
+    refresh?: boolean;
+}
+/** The aggregate result of a full {@link validateConfig} pass. */
+interface ValidateResult {
+    sequences: readonly SequenceValidationResult[];
+    /** All accumulated warnings (draft Templates that could not be confirmed) — surfaced, not fatal. */
+    warnings: readonly string[];
+}
+/**
+ * The full config-time validation entry point — the function `envoy.validate()` wraps (U18 / R45).
+ * Runs, in order:
+ *   1. the SYNCHRONOUS watermark-column checks (no network — fails loud on a nullable declaration), then
+ *   2. the LAZY slot⇄Template network checks for every passed sequence (fails loud on a missing slot).
+ *
+ * Synchronous checks run FIRST so a nullable-column or bad-type mistake fails without spending a
+ * Resend round-trip. Never runs at module load — the host calls it explicitly (or the engine calls it
+ * lazily on first tick), preserving U3's unset-key no-op for installs that never validate.
+ *
+ * @throws {ValidationError} on the first hard failure (nullable watermark, unknown stream/type, or a
+ *   missing slot). Warnings (draft Templates) are returned, never thrown.
+ */
+declare function validateConfig(envoy: Envoy, input: ValidateInput): Promise<ValidateResult>;
+
+declare const SDK_VERSION = "0.0.0";
+
+export { type AdvanceOptions, type AdvanceResult, type AgentCallOpts, AgentError, type AgentSessionResult, type Authorize, type AuthorizeResult, type BroadcastClaimRow, type BroadcastProgram, BroadcastProgramError, BroadcastRenderError, type BroadcastVariables, CONSENT_RANK, type ClaimResult, ConsentMirror, type ConsentRow, type ConsentSetInput, type ConsentSetResult, type ConsentStatus, type ContactInput, type CreateTokenInput, type CronTickResponse, type CursorKey, type CursorState, DEFAULT_PRECHECK_MAX_PAGES, DEFAULT_PRECHECK_PAGE_SIZE, DEFAULT_PRECHECK_RETRIES, DEFAULT_PRECHECK_RETRY_DELAY_MS, DEFAULT_UNSUB_RATE_LIMIT, DEFAULT_UNSUB_RATE_WINDOW_SECONDS, type DefineBroadcastProgramInput, type DefineSequenceInput, type DeleteContactResult, type DripCronHandlerConfig, type DripEngineConfig, type DripSkipReason, type DripStepResult, type DripTickConfig, type DripTickItem, type DripTickResult, type DueOptions, type DueStep, type EnrollOptions, type EnrollResult, type Envoy, type EnvoyAgentConfig, type EnvoyConfig, EnvoyConfigError, type EnvoyHandlerConfig, EnvoyNamespaceError, type EnvoyRouteHandlers, type EnvoyStreamConfig, type FetchedTemplate, type GenerateOrHarvestInput, type GenerateSlotsInput, type GeneratedSlots, type HarvestResult, type IssueSkipReason, type ListUnsubscribeHeaders, SERVER_INSTRUCTIONS as MCP_SERVER_INSTRUCTIONS, MIN_UNSUBSCRIBE_TTL_SECONDS, type McpProgramRegistry, type McpRouteConfig, type McpSequenceRegistry, type McpVerifyToken, type MigrateOptions, type MigrateResult, NamespacedDb, type ProgramRender, type ProgramTopic, type ProvisionTopicInput, type ProvisionTopicResult, type RateLimitResult, type ReconcileContactInput, type ReconcileContactResult, type ReconcileOptions, type ReconcileOutcome, type ReconcileSweepResult, type RenderBroadcastInput, type RenderContext, type RenderedBroadcast, type RenderedIssue, type ResendClientHandle, type ResendWebhookEvent, type ResolvedEnvoyConfig, type ResumePrecheckOptions, type ResumeResolution, type RunIssueInput, type RunIssueResult, SDK_VERSION, STREAMS, type SdkPool, type SdkQueryResult, type SegmentOpResult, SegmentSync, type SendBroadcastInput, type SendBroadcastResult, type Sequence, SequenceDefinitionError, type SequenceRegistry, type SequenceStep, type SequenceValidationResult, type SlotGenerationResult, type StepSlotCheck, type Stream, type SubHandler, type SyncPushInput, type SyncPushResult, type SyncTopic, TemplateFetchError, type TemplateVariableSpec, type TransactionalSendConfig, TransactionalSendError, type TransactionalSendInput, type TransactionalSendResult, type TransactionalSkipReason, type TransactionalVariables, type UnsubscribeClaims, type UnsubscribeLandingConfig, type ValidateInput, type ValidateResult, ValidationError, type VerifyResult, type WatermarkColumnDeclaration, type WebhookIngestResult, addToSegment, advance as advanceCursor, assertTransactionalStream, assertWatermarkColumnType, buildListUnsubscribeHeaders, buildSlotGoal, checkRateLimit, claim, clearTemplateCache, clearValidationCache, clientIp, computeNamespaceFingerprint, createConsentMirror, createDb, createDripCronHandler, createEnvoy, createEnvoyHandler, createMcpRouteHandler as createEnvoyMcpHandler, createMcpRouteHandler, createResendClientHandle, createSegmentSync, createUnsubscribeToken, createWebhookReceiver, due as cursorDue, defaultVerifyMcpToken, defineBroadcastProgram, defineSequence, deleteContact, enroll, extractRecipientEmail, extractSlots, generateOrHarvestSlots, getAgentClient, getTemplate, handleUnsubscribe, harvestAgentSession, ingestEvent, markSent, migrate, normalizeEmail, persistBroadcastId, provisionTopic, read as readCursor, reconcile, reconcileContact, redactEmail, redactValue, registerEnvoyTools, removeFromSegment, renderBroadcast, resolveConfig, resolveResumeBroadcastId, resolveSubpath, runAgentSession, runDripStep, sanitizeContactForAgent, sendBroadcast, sendTransactional, setAgentClient, setPaused as setCursorPaused, tickDrip, topicKeyFor, tryAdvance as tryAdvanceCursor, validateConfig, validateSequenceSlots, validateSequences, verifyUnsubscribeToken };