@pramen/server 0.0.58 → 0.0.60

package/dist/runtime/data-migrations.js

@@ -0,0 +1,256 @@
+// Data migrations — the imperative, recorded half of schema evolution.
+//
+// `migrate()` (runtime/migrate.ts) is declarative: it diffs the live table shape against
+// the declared schema and enacts the structural delta. A diff between two SHAPES can only
+// ever express structure, never TRANSFORMATION — it cannot split `name` into
+// `firstName`/`lastName`, backfill the nullable column `ADD COLUMN` just created (SQLite
+// can't add NOT NULL to a populated table, so every new column starts as a hole), rewrite
+// `priceHalers` → `priceCzk`, or normalize a `t.json()` blob whose shape changed.
+//
+// So: structure stays declarative, data becomes imperative, ordered, and RECORDED. Each
+// `app.migrations` entry runs at most once per `(id, partition)`, its ledger row written in
+// `_pramen_migrations` in the SAME transaction as the work. That is what makes a
+// non-idempotent transformation safe, and it is precisely why `app.bootstrap` cannot be
+// stretched to cover this (bootstrap runs on EVERY boot, must be idempotent, and swallows
+// its errors).
+//
+// Fail closed. A throwing migration records no ledger row, does not let the boot complete,
+// and propagates — the tenant's request fails and the migration is retried on the next
+// fetch. This mirrors migrate()'s "withhold the schema hash on a skip" invariant: the store
+// is never marked as having reached a state it did not reach.
+//
+// CLAIM FIRST, UNDER A LEASE. The ledger row is taken BEFORE the work — one atomic upsert
+// that inserts a pending row, or steals one whose lease has expired, or does nothing — and
+// the migration runs only if that statement won the row. On the DO this is merely bookkeeping
+// order inside one transaction. On D1 it is what makes the once-only contract hold at all:
+// there is no single writer and no interactive transaction, `d1Ready` is per-isolate, so two
+// cold isolates racing a `SET n = n * 2` backfill would each read an empty ledger, each run
+// it, and quadruple the data. The conflicting upsert is the lock.
+//
+// The row therefore has two states, distinguished by `leaseUntil`: IN FLIGHT (non-NULL — a
+// runner holds it until that instant) and APPLIED (NULL). Only an applied row counts as
+// applied, so an in-flight migration reads as pending everywhere, including the admin ledger.
+//
+// A runner that finds a LIVE lease does not skip — skipping would let it serve traffic
+// against half-migrated data, and would strand the migration entirely if the holder then
+// failed. It waits for the holder, up to WAIT_BUDGET_MS, and then either proceeds (the holder
+// committed), takes the row (the holder released it), or fails closed. A holder that dies
+// without releasing — an isolate evicted mid-backfill, which no compensating DELETE can
+// cover — is recovered by the lease simply expiring.
+//
+// Written against the `Driver`/`Dialect` seam only (no `cloudflare:workers`), so the same
+// runner drives the DO boot path and the D1/Worker path.
+import { DEFAULT_PARTITION, partitionsOf } from "../sdk/schema";
+export const MIGRATIONS_TABLE = "_pramen_migrations";
+/** Create the ledger if absent. Idempotent — run on every boot before the runner and from
+ * the /__migrations endpoint (a DO that has never applied one still answers). Internal
+ * table (`_pramen_` prefix), so `isInternalTable()` keeps the migrator's hands off it.
+ *
+ * `partition` is a reserved-ish word in some engines, so every identifier goes through
+ * `dialect.id(...)` (the single `quoteIdent` source of truth) rather than being interpolated
+ * bare — here and in every query below. */
+export async function ensureMigrationsTable(driver) {
+    const d = driver.dialect;
+    const t = d.id(MIGRATIONS_TABLE);
+    await driver.exec(`CREATE TABLE IF NOT EXISTS ${t} (` +
+        `${d.id("id")} TEXT NOT NULL, ${d.id("partition")} TEXT NOT NULL, ${d.id("appliedAt")} TEXT NOT NULL, ` +
+        `${d.id("leaseUntil")} INTEGER, PRIMARY KEY (${d.id("id")}, ${d.id("partition")}))`, []);
+    // `leaseUntil` was added after the table's first shape. Probe for it with a zero-row SELECT
+    // rather than PRAGMA table_info: the PRAGMA is what workerd's DO SQLite authorizer starts
+    // rejecting (SQLITE_AUTH) once the alarm API has run in the object, and this runs on every
+    // boot. Adding a nullable column is a plain ALTER — no rebuild, and existing rows read as
+    // applied, which is what they are.
+    const hasLease = await driver
+        .exec(`SELECT ${d.id("leaseUntil")} FROM ${t} LIMIT 0`, [])
+        .then(() => true)
+        .catch(() => false);
+    if (!hasLease)
+        await driver.exec(`ALTER TABLE ${t} ADD COLUMN ${d.id("leaseUntil")} INTEGER`, []);
+}
+/** Ledger rows for one partition — or every partition when `partition` is omitted (the D1
+ * store, which holds one shared ledger for all of them). Oldest first. */
+export async function appliedMigrations(driver, partition) {
+    const d = driver.dialect;
+    // `leaseUntil IS NULL` is the definition of applied: a row a runner is still holding is
+    // in flight, and must read as PENDING everywhere — the admin ledger and the CLI included.
+    const scope = partition === undefined ? "" : ` AND ${d.id("partition")} = ${d.placeholder(1)}`;
+    const where = ` WHERE ${d.id("leaseUntil")} IS NULL${scope}`;
+    const rows = await driver.exec(`SELECT ${d.id("id")}, ${d.id("partition")}, ${d.id("appliedAt")} FROM ${d.id(MIGRATIONS_TABLE)}${where} ` +
+        `ORDER BY ${d.id("appliedAt")}, ${d.id("id")}`, partition === undefined ? [] : [d.encode(partition)]);
+    return rows.map((r) => ({ id: String(r.id), partition: String(r.partition), appliedAt: String(r.appliedAt) }));
+}
+/** The migrations that belong to `partition`: an entry with no declared partition belongs
+ * to the default one. Both boot paths select through this, so "which partition owns this
+ * migration" is answered in exactly one place. */
+export function migrationsForPartition(migrations, partition) {
+    return migrations.filter((m) => (m.partition ?? DEFAULT_PARTITION) === partition);
+}
+export const DEFAULT_LEASE = { ttlMs: 60_000, waitMs: 5_000, pollMs: 100 };
+/** Run every pending migration, in DECLARATION order, each inside its own
+ * `driver.transaction()`, CLAIMING its ledger row before it runs the work — so "the work
+ * happened" and "the work is recorded" cannot come apart on a substrate with real
+ * transactions (the DO), and cannot double-run on one without (D1). A migration whose claim
+ * loses the race (another isolate holds it, or a previous boot applied it) is skipped.
+ *
+ * D1 CAVEAT: `D1Driver.transaction(fn)` is `fn()` (D1 has no interactive transactions), so
+ * there the claim and the work do NOT commit together. A throw therefore RELEASES the claim
+ * explicitly (a compensating DELETE, issued inside the transaction so the DO simply rolls it
+ * back with everything else) — otherwise a failed migration would stay marked as applied,
+ * which is the one outcome the fail-closed contract exists to prevent. A holder that dies
+ * without reaching that DELETE is covered by the lease expiring instead. Prefer SQL that
+ * tolerates a re-run (`WHERE col IS NULL`) when the D1 store is in play: a mid-flight failure
+ * leaves the partial writes behind.
+ *
+ * Fails CLOSED: the first throw aborts the run, so migrations declared after it do not run
+ * either (order is a contract — a later one may depend on an earlier one's output). */
+export async function runDataMigrations(driver, migrations, opts) {
+    const applied = [];
+    const skipped = [];
+    const pending = opts.partition === undefined ? migrations : migrationsForPartition(migrations, opts.partition);
+    if (pending.length === 0)
+        return { applied, skipped };
+    const lease = { ...DEFAULT_LEASE, ...opts.lease };
+    await ensureMigrationsTable(driver);
+    const done = new Set((await appliedMigrations(driver, opts.partition)).map((r) => ledgerKey(r.id, r.partition)));
+    for (const m of pending) {
+        const partition = m.partition ?? DEFAULT_PARTITION;
+        // The cheap pre-check: skip without opening a transaction for what a previous boot
+        // already applied (the common case — every boot after the first). `claim` is what
+        // actually decides; this only keeps the steady state free of no-op transactions.
+        if (done.has(ledgerKey(m.id, partition))) {
+            skipped.push(m.id);
+            continue;
+        }
+        let ran = false;
+        try {
+            await driver.transaction(async () => {
+                // Take the row, waiting out any live lease. "applied" means another runner finished
+                // it while we waited — nothing left to do, and we now know the data IS migrated.
+                if ((await acquire(driver, m.id, partition, lease)) === "applied")
+                    return;
+                ran = true;
+                try {
+                    await m.up(opts.makeContext(partition));
+                    await complete(driver, m.id, partition);
+                }
+                catch (e) {
+                    await release(driver, m.id, partition); // no-op on the DO (rolled back anyway)
+                    throw e;
+                }
+            });
+        }
+        catch (e) {
+            // Name the migration in the message: the raw SQL error alone gives no clue WHICH of
+            // an ordered list failed, and the boot it aborted is the tenant's first request.
+            throw new Error(`[pramen] data migration ${JSON.stringify(m.id)} failed (partition=${partition}): ` +
+                `${e instanceof Error ? e.message : String(e)}`, { cause: e });
+        }
+        if (!ran) {
+            skipped.push(m.id);
+            continue;
+        }
+        console.log(`[pramen] data migration ${JSON.stringify(m.id)} applied (partition=${partition})`);
+        applied.push(m.id);
+    }
+    return { applied, skipped };
+}
+/** The ledger is keyed by (id, partition) — the same reason the schema hash is
+ * `schema_hash:<partition>`: partitions are independent DOs and must not thrash each
+ * other's state. NUL-joined, so no (id, partition) pair can collide with another. */
+const ledgerKey = (id, partition) => `${id}\u0000${partition}`;
+/** ONE atomic statement that does all three things a claim must: insert the row when the
+ * migration is pending, STEAL it when a previous holder's lease has expired (that holder is
+ * presumed dead — an isolate evicted mid-backfill releases nothing), and do nothing when the
+ * row is applied or a live lease holds it. `RETURNING` fires only when a row was actually
+ * written, so it reports which happened. The upsert's `WHERE` is what confines the steal to
+ * an expired lease: without it this would be a plain overwrite and two live runners would
+ * both "win". */
+async function tryClaim(driver, id, partition, now, ttlMs) {
+    const d = driver.dialect;
+    const t = d.id(MIGRATIONS_TABLE);
+    const params = [id, partition, new Date(now).toISOString(), now + ttlMs, now];
+    const rows = await driver.exec(`INSERT INTO ${t} (${d.id("id")}, ${d.id("partition")}, ${d.id("appliedAt")}, ${d.id("leaseUntil")}) ` +
+        `VALUES (${d.placeholder(1)}, ${d.placeholder(2)}, ${d.placeholder(3)}, ${d.placeholder(4)}) ` +
+        `ON CONFLICT (${d.id("id")}, ${d.id("partition")}) DO UPDATE SET ` +
+        `${d.id("appliedAt")} = excluded.${d.id("appliedAt")}, ${d.id("leaseUntil")} = excluded.${d.id("leaseUntil")} ` +
+        `WHERE ${t}.${d.id("leaseUntil")} IS NOT NULL AND ${t}.${d.id("leaseUntil")} <= ${d.placeholder(5)} ` +
+        `RETURNING ${d.id("id")}`, params.map((v) => d.encode(v)));
+    if (rows.length > 0)
+        return "claimed";
+    // Nothing written — so the row exists and we did not qualify. Which of the two is it?
+    const [row] = await driver.exec(`SELECT ${d.id("leaseUntil")} FROM ${t} WHERE ${d.id("id")} = ${d.placeholder(1)} AND ${d.id("partition")} = ${d.placeholder(2)}`, [id, partition].map((v) => d.encode(v)));
+    // Gone between the two statements (a holder released it) — contended, not applied.
+    if (!row)
+        return "held";
+    return row.leaseUntil == null ? "applied" : "held";
+}
+/** Take the row, waiting out a live lease. Returns "applied" when someone else finished it
+ * while we waited — in which case the caller must NOT run the migration, but CAN proceed
+ * knowing the data is migrated. That distinction is the point: skipping a live lease outright
+ * (the previous behavior) let a runner serve traffic against half-migrated data, and stranded
+ * the migration on that isolate entirely if the holder then failed.
+ *
+ * On the DO this never waits — one Durable Object is a single writer and the migration runs
+ * inside `blockConcurrencyWhile`, so a second concurrent first-fetch is queued by the platform
+ * rather than contending here. The wait exists for D1, where nothing serializes isolates. */
+async function acquire(driver, id, partition, lease) {
+    const deadline = Date.now() + lease.waitMs;
+    for (;;) {
+        const outcome = await tryClaim(driver, id, partition, Date.now(), lease.ttlMs);
+        if (outcome !== "held")
+            return outcome;
+        if (Date.now() >= deadline) {
+            // Fail closed rather than guess. Another runner is mid-flight; the request retries and
+            // will usually find it applied. Serving on through a migration we know is unfinished is
+            // the one thing that must not happen.
+            throw new Error(`another runner holds the lease and did not finish within ${lease.waitMs}ms`);
+        }
+        await new Promise((r) => setTimeout(r, lease.pollMs));
+    }
+}
+/** Mark the migration applied: drop the lease (NULL is the definition of applied) and stamp
+ * the instant the work actually committed rather than the one the claim was taken. */
+async function complete(driver, id, partition) {
+    const d = driver.dialect;
+    await driver.exec(`UPDATE ${d.id(MIGRATIONS_TABLE)} SET ${d.id("appliedAt")} = ${d.placeholder(1)}, ${d.id("leaseUntil")} = NULL ` +
+        `WHERE ${d.id("id")} = ${d.placeholder(2)} AND ${d.id("partition")} = ${d.placeholder(3)}`, [new Date().toISOString(), id, partition].map((v) => d.encode(v)));
+}
+/** Give the claim back after a failed `up()`, so the next runner retries immediately instead
+ * of waiting out the lease. Only observable where `transaction()` does not roll back (D1); on
+ * the DO the enclosing transaction discards this along with the claim itself. Guarded on
+ * `leaseUntil IS NOT NULL` so it can only ever delete an IN-FLIGHT row — never an applied one,
+ * whatever else has happened to the ledger in between. */
+async function release(driver, id, partition) {
+    const d = driver.dialect;
+    await driver.exec(`DELETE FROM ${d.id(MIGRATIONS_TABLE)} WHERE ${d.id("id")} = ${d.placeholder(1)} AND ${d.id("partition")} = ${d.placeholder(2)} ` +
+        `AND ${d.id("leaseUntil")} IS NOT NULL`, [id, partition].map((v) => d.encode(v)));
+}
+/** Static validation, called from `createPramen` next to `validateTriggerTasks` — these are
+ * declaration bugs, and the only honest time to surface them is before a single tenant has
+ * booted. Throws on the first violation:
+ *
+ *  - an empty id (the ledger key would be meaningless);
+ *  - a duplicate id — ids are GLOBALLY unique across the array, not per partition, so a
+ *    copy-pasted id can never quietly mark a different migration as already applied;
+ *  - a declared `partition` no entity lives in — the migration would be dead code on the
+ *    DO path (no DO serves that partition) while still running on D1. */
+export function validateMigrations(schema, migrations) {
+    if (!migrations?.length)
+        return;
+    const known = new Set(partitionsOf(schema));
+    known.add(DEFAULT_PARTITION); // always addressable, even for a schema with no entities
+    const seen = new Set();
+    for (const m of migrations) {
+        if (!m.id)
+            throw new Error("app.migrations: every migration needs a non-empty, stable `id` (it is the ledger key).");
+        if (seen.has(m.id)) {
+            throw new Error(`app.migrations: duplicate id ${JSON.stringify(m.id)}. Ids are the ledger key and must be globally ` +
+                `unique — a reused id makes one of the two silently a no-op.`);
+        }
+        seen.add(m.id);
+        if (m.partition !== undefined && !known.has(m.partition)) {
+            throw new Error(`app.migrations: migration ${JSON.stringify(m.id)} declares partition ${JSON.stringify(m.partition)}, ` +
+                `which no entity lives in. Known partitions: ${[...known].join(", ")}.`);
+        }
+    }
+}

package/dist/runtime/mail.d.ts

@@ -47,6 +47,33 @@ export declare class CloudflareEmailAdapter implements MailAdapter {
         from: MailAddress;
     }): Promise<void>;
 }
+/** Mailgun — an HTTP transport, for when Cloudflare Email Sending cannot be used.
+ *
+ * Worth the key for one reason: Cloudflare will only send from a domain that is a zone
+ * in the same account, and some accounts additionally refuse any recipient that is not a
+ * verified destination in Email Routing ("destination address is not a verified
+ * address"). That is workable for a handful of operators and hopeless for real users.
+ * Mailgun asks the domain be verified once, then delivers to anyone.
+ *
+ * A non-2xx THROWS, deliberately: `ctx.mail.send` is normally called from a task, and a
+ * throw is what makes the outbox retry and then dead-letter visibly. Swallowing the
+ * status would turn a bounced sign-in link into silence. The response body rides along
+ * in the message because Mailgun's 400s are specific and worth reading ("not a valid
+ * address", "domain not found"); the key never does. */
+export declare class MailgunAdapter implements MailAdapter {
+    private readonly apiKey;
+    private readonly domain;
+    /** `https://api.eu.mailgun.net` for an EU-region account; the two are separate
+     * deployments and a key from one 401s against the other. */
+    private readonly apiBase;
+    constructor(apiKey: string, domain: string, 
+    /** `https://api.eu.mailgun.net` for an EU-region account; the two are separate
+     * deployments and a key from one 401s against the other. */
+    apiBase?: string);
+    send(message: MailMessage & {
+        from: MailAddress;
+    }): Promise<void>;
+}
 /** Dev/test transport: stash the message in KV under `mail:<recipient>` so an e2e suite
  * (or a dashboard) can read the "inbox" instead of really sending. */
 export declare class KvMailAdapter implements MailAdapter {
@@ -73,9 +100,14 @@ export declare class UnconfiguredMailAdapter implements MailAdapter {
     send(): Promise<void>;
 }
 /** Build `ctx.mail` from the environment:
- *  - `EMAIL` binding + `MAIL_FROM` → Cloudflare Email Sending (real send).
+ *  - `MAILGUN_API_KEY` + `MAILGUN_DOMAIN` + `MAIL_FROM` → Mailgun (real send).
+ *  - else `EMAIL` binding + `MAIL_FROM` → Cloudflare Email Sending (real send).
  *  - else `MAIL_CAPTURE=true` → capture (KV inbox if a Kv is given, else in-memory) with
  *    a synthetic dev sender — an EXPLICIT dev opt-in, never the production default.
  *  - else → fail closed: a `send` throws (so a missing-MAIL_FROM prod doesn't silently
- *    stash security emails in KV). */
+ *    stash security emails in KV).
+ *
+ * Mailgun outranks the binding on purpose. The binding tends to be present because the
+ * infrastructure declares it, whereas an API key is only ever there because somebody put
+ * it there — so when both exist, the key is the newer decision. */
 export declare function createMail(env: EnvBag, kv?: Kv): Mail;

package/dist/runtime/mail.js

@@ -5,10 +5,15 @@
 //
 //   await ctx.mail.send({ to: "u@x.com", subject: "Welcome", text: "…" });
 //
-// On Cloudflare the transport is Cloudflare Email Sending (the `send_email`/`EMAIL`
-// binding, no API keys). With no verified sender configured (local/dev), mail is
-// captured instead of sent — to KV (so an e2e/dashboard can read the "inbox") or
-// in-memory — so handlers work unchanged off-platform.
+// Two real transports. Cloudflare Email Sending (the `send_email`/`EMAIL` binding) needs
+// no API keys, but it can only send FROM a domain that is a zone in the same account,
+// and on some accounts only TO addresses verified in Email Routing — which rules it out
+// whenever the recipients are ordinary people. Mailgun is the way out of both: an HTTP
+// API, any recipient, at the cost of a key. Configure it and it wins.
+//
+// With neither configured (local/dev), mail is captured instead of sent — to KV (so an
+// e2e/dashboard can read the "inbox") or in-memory — so handlers work unchanged
+// off-platform.
 /** The `ctx.mail` facade: resolves the sender, validates, and delegates to the adapter. */
 export class Mail {
     adapter;
@@ -49,6 +54,60 @@ export class CloudflareEmailAdapter {
         });
     }
 }
+/** Mailgun — an HTTP transport, for when Cloudflare Email Sending cannot be used.
+ *
+ * Worth the key for one reason: Cloudflare will only send from a domain that is a zone
+ * in the same account, and some accounts additionally refuse any recipient that is not a
+ * verified destination in Email Routing ("destination address is not a verified
+ * address"). That is workable for a handful of operators and hopeless for real users.
+ * Mailgun asks the domain be verified once, then delivers to anyone.
+ *
+ * A non-2xx THROWS, deliberately: `ctx.mail.send` is normally called from a task, and a
+ * throw is what makes the outbox retry and then dead-letter visibly. Swallowing the
+ * status would turn a bounced sign-in link into silence. The response body rides along
+ * in the message because Mailgun's 400s are specific and worth reading ("not a valid
+ * address", "domain not found"); the key never does. */
+export class MailgunAdapter {
+    apiKey;
+    domain;
+    apiBase;
+    constructor(apiKey, domain, 
+    /** `https://api.eu.mailgun.net` for an EU-region account; the two are separate
+     * deployments and a key from one 401s against the other. */
+    apiBase = "https://api.mailgun.net") {
+        this.apiKey = apiKey;
+        this.domain = domain;
+        this.apiBase = apiBase;
+    }
+    async send(message) {
+        const body = new URLSearchParams();
+        body.set("from", message.from.name ? `${message.from.name} <${message.from.email}>` : message.from.email);
+        for (const to of Array.isArray(message.to) ? message.to : [message.to])
+            body.append("to", to);
+        body.set("subject", message.subject);
+        if (message.text)
+            body.set("text", message.text);
+        if (message.html)
+            body.set("html", message.html);
+        if (message.replyTo) {
+            const r = message.replyTo;
+            body.set("h:Reply-To", typeof r === "string" ? r : r.name ? `${r.name} <${r.email}>` : r.email);
+        }
+        const res = await fetch(`${this.apiBase.replace(/\/+$/, "")}/v3/${encodeURIComponent(this.domain)}/messages`, {
+            method: "POST",
+            headers: {
+                // `api` is the literal username Mailgun expects; the key is the password.
+                authorization: `Basic ${btoa(`api:${this.apiKey}`)}`,
+                "content-type": "application/x-www-form-urlencoded",
+            },
+            body,
+        });
+        if (!res.ok) {
+            const detail = await res.text().catch(() => "");
+            throw new Error(`mailgun: send failed (${res.status})${detail ? ` — ${detail.slice(0, 300)}` : ""}`);
+        }
+    }
+}
 /** Dev/test transport: stash the message in KV under `mail:<recipient>` so an e2e suite
  * (or a dashboard) can read the "inbox" instead of really sending. */
 export class KvMailAdapter {
@@ -76,21 +135,35 @@ export class MemoryMailAdapter {
  * instead of delivering them. Mirrors how files fail closed without FILES_SECRET. */
 export class UnconfiguredMailAdapter {
     async send() {
-        throw new Error("ctx.mail: no transport configured — set MAIL_FROM (with the EMAIL binding) to send, " +
-            "or MAIL_CAPTURE=true to capture in dev.");
+        throw new Error("ctx.mail: no transport configured — set MAIL_FROM with either the EMAIL binding " +
+            "or MAILGUN_API_KEY + MAILGUN_DOMAIN to send, or MAIL_CAPTURE=true to capture in dev.");
     }
 }
 /** Build `ctx.mail` from the environment:
- *  - `EMAIL` binding + `MAIL_FROM` → Cloudflare Email Sending (real send).
+ *  - `MAILGUN_API_KEY` + `MAILGUN_DOMAIN` + `MAIL_FROM` → Mailgun (real send).
+ *  - else `EMAIL` binding + `MAIL_FROM` → Cloudflare Email Sending (real send).
  *  - else `MAIL_CAPTURE=true` → capture (KV inbox if a Kv is given, else in-memory) with
  *    a synthetic dev sender — an EXPLICIT dev opt-in, never the production default.
  *  - else → fail closed: a `send` throws (so a missing-MAIL_FROM prod doesn't silently
- *    stash security emails in KV). */
+ *    stash security emails in KV).
+ *
+ * Mailgun outranks the binding on purpose. The binding tends to be present because the
+ * infrastructure declares it, whereas an API key is only ever there because somebody put
+ * it there — so when both exist, the key is the newer decision. */
 export function createMail(env, kv) {
     const binding = env.EMAIL;
     const fromAddr = typeof env.MAIL_FROM === "string" && env.MAIL_FROM ? env.MAIL_FROM : undefined;
+    const str = (k) => typeof env[k] === "string" && env[k] ? env[k] : undefined;
+    const name = typeof env.MAIL_FROM_NAME === "string" ? env.MAIL_FROM_NAME : undefined;
+    const mailgunKey = str("MAILGUN_API_KEY");
+    const mailgunDomain = str("MAILGUN_DOMAIN");
+    if (mailgunKey && mailgunDomain && fromAddr) {
+        return new Mail(new MailgunAdapter(mailgunKey, mailgunDomain, str("MAILGUN_API_BASE")), {
+            email: fromAddr,
+            name,
+        });
+    }
     if (binding && fromAddr) {
-        const name = typeof env.MAIL_FROM_NAME === "string" ? env.MAIL_FROM_NAME : undefined;
         return new Mail(new CloudflareEmailAdapter(binding), { email: fromAddr, name });
     }
     if (env.MAIL_CAPTURE === "true") {

package/dist/sdk/acl.d.ts

@@ -44,11 +44,19 @@ export interface NowMarker {
  * future timestamp is non-null, so a scheduled row would be readable the moment it
  * is saved.
  *
- * Comparison is lexicographic TEXT, which is exact for ISO-8601 UTC but NOT
- * cross-format: `expr.now()` defaults store `'YYYY-MM-DD HH:MM:SS'` (space, no `Z`)
- * and will not compare correctly against this. Store the column with
- * `toISOString()` — as the CMS `publish` field does — or compare it against
- * `expr.now()`-shaped values only. */
+ * Comparison is lexicographic TEXT, which is exact WITHIN one format and wrong across two.
+ * Both `'YYYY-MM-DD HH:MM:SS'` and the ISO form open with the same date, so values on
+ * different dates still order correctly — it is the SAME date that breaks, where index 10
+ * decides and a space (0x20) always sorts below `T` (0x54). A space-form value dated today
+ * therefore compares as less than this marker whatever its time-of-day, so a row scheduled
+ * for later today reads as already past. The column must hold ISO-8601 UTC —
+ * `new Date().toISOString()`.
+ *
+ * `expr.now()` produces exactly that, so a column defaulted with it is directly comparable
+ * here. It did NOT always: it emitted the `datetime('now')` space form, and a policy over
+ * such a column was a time boundary that silently did not hold. A store written by a build
+ * from before that change still holds space-form values until
+ * `isoTimestampBackfill()` rewrites them. */
 export declare function $now(): NowMarker;
 export declare function isNowMarker(v: WhereValue): v is NowMarker;
 export interface AllowMarker {

package/dist/sdk/acl.js

@@ -40,11 +40,19 @@ const NOW_MARKER = Symbol.for("pramen.nowMarker");
  * future timestamp is non-null, so a scheduled row would be readable the moment it
  * is saved.
  *
- * Comparison is lexicographic TEXT, which is exact for ISO-8601 UTC but NOT
- * cross-format: `expr.now()` defaults store `'YYYY-MM-DD HH:MM:SS'` (space, no `Z`)
- * and will not compare correctly against this. Store the column with
- * `toISOString()` — as the CMS `publish` field does — or compare it against
- * `expr.now()`-shaped values only. */
+ * Comparison is lexicographic TEXT, which is exact WITHIN one format and wrong across two.
+ * Both `'YYYY-MM-DD HH:MM:SS'` and the ISO form open with the same date, so values on
+ * different dates still order correctly — it is the SAME date that breaks, where index 10
+ * decides and a space (0x20) always sorts below `T` (0x54). A space-form value dated today
+ * therefore compares as less than this marker whatever its time-of-day, so a row scheduled
+ * for later today reads as already past. The column must hold ISO-8601 UTC —
+ * `new Date().toISOString()`.
+ *
+ * `expr.now()` produces exactly that, so a column defaulted with it is directly comparable
+ * here. It did NOT always: it emitted the `datetime('now')` space form, and a policy over
+ * such a column was a time boundary that silently did not hold. A store written by a build
+ * from before that change still holds space-form values until
+ * `isoTimestampBackfill()` rewrites them. */
 export function $now() {
     return { [NOW_MARKER]: true };
 }

package/dist/sdk/handlers.d.ts

@@ -73,6 +73,47 @@ export interface BootstrapContext<S extends SchemaDef = SchemaDef> {
  * blind-insert. A thrown error is logged and swallowed so a broken reconcile can't brick a
  * tenant's boot; it simply retries on the next boot. Set as `app.bootstrap`. */
 export type BootstrapFn = (ctx: BootstrapContext) => void | Promise<void>;
+/** Context handed to a data migration's `up()`. Same privileged, SYSTEM-scoped shape as
+ * `BootstrapContext` (ACL bypassed, triggers suppressed) but scoped to the migration's
+ * own `partition` — each partition-DO runs its own partition's migrations, so `db`/`driver`
+ * here address exactly that DO's tables. */
+export interface MigrationContext<S extends SchemaDef = SchemaDef> {
+    /** System-scoped Db (ACL bypassed), triggers suppressed, scoped to `partition`. */
+    readonly db: Db<S>;
+    /** Raw driver — a bulk `UPDATE`/`INSERT … SELECT` is usually the right tool for a
+     * backfill; going row-by-row through `db` on a large table is what blows the DO's
+     * wall-clock budget. */
+    readonly driver: Driver;
+    readonly schema: S;
+    /** The partition this migration is running (and being recorded) under. */
+    readonly partition: string;
+}
+/** One imperative, ORDERED, recorded-once transformation of existing DATA — the half a
+ * declarative diff cannot express: split a column, backfill the nullable column `ADD COLUMN`
+ * just created, rewrite units, normalize a `t.json()` blob after its shape changed.
+ *
+ * The deliberate inverse of `BootstrapFn` on every axis that matters: it runs ONCE ever
+ * (recorded in `_pramen_migrations` keyed by `(id, partition)`), so it need NOT be
+ * idempotent — a backfill that would double a value on a second run is exactly what this
+ * exists for; and a throw is NOT swallowed. It fails CLOSED: no ledger row, the boot does
+ * not complete, the request fails, and the migration is retried on the tenant's next fetch.
+ * Silently marking a half-finished backfill as done is the one outcome worth bricking a
+ * boot to avoid.
+ *
+ * Runs after `migrate()` (so the column exists) and before `app.bootstrap`. There are no
+ * DOWN migrations. Set as `app.migrations`. */
+export interface DataMigration {
+    /** Stable, unique, never reused — this is the ledger key. Deleting an id from the array
+     * does NOT un-apply it; and a cold tenant is unmigrated until touched, so an id can only
+     * be pruned once EVERY live tenant reports it applied (`pramen migrations status
+     * --all-tenants`). */
+    id: string;
+    /** Restrict to one partition; default = the default partition. Only that partition's DO
+     * runs it (its tables live in no other DO). The D1 store is one shared database with no
+     * partition split, so there every migration runs — still recorded under this key. */
+    partition?: string;
+    up(ctx: MigrationContext): void | Promise<void>;
+}
 /** The deferred-side-effects facade handed to handlers as `ctx.tasks`. */
 export interface Tasks {
     /** Enqueue a task to run after commit. `kind` selects the `app.tasks` handler;

package/dist/sdk/iso-timestamps.d.ts

@@ -0,0 +1,54 @@
+import type { DataMigration } from "./handlers";
+import type { SchemaDef } from "./schema";
+/** The old default's SQL, for recognizing a column that carried it. */
+export declare const LEGACY_NOW_SQL = "datetime('now')";
+/** Columns to rewrite beyond the ones the schema identifies, as `{ table: [column, …] }`.
+ *
+ * The schema can only find columns whose DEFAULT is `expr.now()`. A column written by
+ * HANDLER code in the same space form — `@pramen/cms` stamped `cms_pages.publishedAt` that
+ * way — has no marker on it at all, so the app has to name it. `@pramen/cms` exports its
+ * own set as `CMS_LEGACY_TIMESTAMP_COLUMNS`. */
+export type ExtraTimestampColumns = Readonly<Record<string, readonly string[]>>;
+export interface IsoTimestampBackfillOpts {
+    /** Ledger id. Defaults to `pramen:iso-timestamps`. Override only if you have already
+     * used that id for something else — it is the key that makes this run once. */
+    id?: string;
+    /** Partition to run in. A partition-DO only sees its own tables, so an app with several
+     * partitions declares one of these per partition, each with its own id. */
+    partition?: string;
+    /** Columns the schema cannot identify — see {@link ExtraTimestampColumns}. */
+    extraColumns?: ExtraTimestampColumns;
+}
+/**
+ * A `DataMigration` that rewrites space-form timestamps to ISO-8601 in place.
+ *
+ * ```ts
+ * import { isoTimestampBackfill } from "@pramen/server";
+ * import { CMS_LEGACY_TIMESTAMP_COLUMNS } from "@pramen/cms";
+ *
+ * export const app = {
+ *   migrations: [isoTimestampBackfill({ extraColumns: CMS_LEGACY_TIMESTAMP_COLUMNS })],
+ *   // …
+ * };
+ * ```
+ *
+ * A **new** deployment can declare it too and pay nothing: every `UPDATE` matches no rows.
+ * Declaring it unconditionally is the cheaper habit, because "was this store ever written
+ * by an older build?" is not a question the code can answer later.
+ *
+ * It is not idempotent-by-accident, it is idempotent-by-shape: the `WHERE` matches only the
+ * space form, and what it writes is not the space form. That matters because a data
+ * migration is not required to be idempotent (it is recorded once) but this one runs over
+ * columns an app may also be writing, and a second pass must not corrupt a converted value.
+ */
+export declare function isoTimestampBackfill(opts?: IsoTimestampBackfillOpts): DataMigration;
+/**
+ * Which `(table, column)` pairs this migration touches — the schema's `expr.now()` columns
+ * in `partition`, plus whatever the app named.
+ *
+ * Exported for the tests and for anyone who wants to see the list before running it. An
+ * extra column naming a table or column that is not in the schema is IGNORED rather than
+ * throwing: the list is a hand-written constant an app may keep across a schema change, and
+ * failing the whole boot over a stale entry in it would be a worse outcome than skipping it.
+ */
+export declare function timestampColumns(schema: SchemaDef, partition?: string, extra?: ExtraTimestampColumns): Map<string, string[]>;