@pramen/server 0.0.58 → 0.0.60

package/src/index.ts

@@ -8,7 +8,10 @@
 // and codegen load an app.ts for its schema without dragging in the DO runtime.
 
 // --- schema authoring ---
-export { Entity, defineSchema, renamedFrom, notNull, unique, indexed, hidden, defaultTo, primaryKey, generated, expr, ExprDefault, trigger, partitionOf, DEFAULT_PARTITION } from "./sdk/schema";
+export { Entity, defineSchema, renamedFrom, notNull, unique, indexed, hidden, defaultTo, primaryKey, generated, expr, ExprDefault, ISO_NOW_SQL, trigger, partitionOf, DEFAULT_PARTITION } from "./sdk/schema";
+// The one-off rewrite that goes with `expr.now()` changing shape — see ./sdk/iso-timestamps.
+export { isoTimestampBackfill, timestampColumns, LEGACY_NOW_SQL } from "./sdk/iso-timestamps";
+export type { ExtraTimestampColumns, IsoTimestampBackfillOpts } from "./sdk/iso-timestamps";
 export type { TriggerDef, TriggerOp } from "./sdk/schema";
 export { isValidUuid } from "./sdk/uuid";
 export type {
@@ -31,7 +34,7 @@ export type {
 // --- app + handlers ---
 export { createApp } from "./sdk/app";
 export { query, mutation, authorizeHandler } from "./sdk/handlers";
-export type { EnvBag, Handler, HandlerContext, HandlerKind, HandlerMap, HandlerOpts, HandlerAuth, Tasks, TaskHandler, AppTaskMap, BootstrapContext, BootstrapFn } from "./sdk/handlers";
+export type { EnvBag, Handler, HandlerContext, HandlerKind, HandlerMap, HandlerOpts, HandlerAuth, Tasks, TaskHandler, AppTaskMap, BootstrapContext, BootstrapFn, MigrationContext, DataMigration } from "./sdk/handlers";
 
 // --- ACL ---
 export { $identity, $input, $now, allow, deny, policy, resolve, role, isAllow, isDeny, isResolver, isIdentityMarker, isInputMarker, isNowMarker } from "./sdk/acl";
@@ -95,7 +98,7 @@ export type { ExpiringToken } from "./runtime/token";
 export type { StorageAdapter, PutResult, GetResult } from "./runtime/storage";
 
 // --- mail (ctx.mail) ---
-export { Mail, CloudflareEmailAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
+export { Mail, CloudflareEmailAdapter, MailgunAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
 export type { MailMessage, MailAddress, MailAdapter, SendEmailBinding } from "./runtime/mail";
 
 // --- queue (ctx.queue — Cloudflare Queues) ---

package/src/pramen.ts

@@ -15,7 +15,8 @@
 import { makeWorker, type Env } from "./worker";
 import { pramenDO, type DoEnv } from "./durable-object";
 import { validateTriggerTasks, type SchemaDef } from "./sdk/schema";
-import type { AppTaskMap, HandlerMap, BootstrapFn } from "./sdk/handlers";
+import { validateMigrations } from "./runtime/data-migrations";
+import type { AppTaskMap, HandlerMap, BootstrapFn, DataMigration } from "./sdk/handlers";
 import type { AppQueueMap, QueueBatch } from "./runtime/queue-consumer";
 import type { Role } from "./sdk/acl";
 import type { EnvBag } from "./sdk/handlers";
@@ -59,6 +60,12 @@ export interface PramenApp {
    * code-defined reference data into the store (see `BootstrapFn`). Each runs with a
    * privileged system Db; failures are logged, never fatal. */
   bootstrap?: readonly BootstrapFn[];
+  /** Imperative DATA migrations — backfills, splits, normalizations — run in declaration
+   * order after `migrate()` and before `bootstrap`, each recorded ONCE per (id, partition)
+   * in `_pramen_migrations` (see `DataMigration`). The declarative migrator diffs shapes
+   * and so can only enact structure; this is the transformation half. Unlike `bootstrap`,
+   * a failure is NOT swallowed — it fails the boot closed and retries next fetch. */
+  migrations?: readonly DataMigration[];
 }
 
 export type { Env, DoEnv };
@@ -73,6 +80,7 @@ export function createPramen(app: PramenApp): {
   PramenDO: ReturnType<typeof pramenDO>;
 } {
   validateTriggerTasks(app.schema, Object.keys(app.tasks ?? {})); // fail fast on a typo'd trigger task
+  validateMigrations(app.schema, app.migrations); // fail fast on a duplicate/empty id or an unknown partition
   const worker = makeWorker(app);
   return { fetch: worker.fetch, scheduled: worker.scheduled, queue: worker.queue, PramenDO: pramenDO(app) };
 }

package/src/runtime/data-migrations.ts

@@ -0,0 +1,343 @@
+// 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, type SchemaDef } from "../sdk/schema";
+import type { DataMigration, MigrationContext } from "../sdk/handlers";
+import type { CellValue } from "../sdk/infer";
+import type { Driver } from "./driver";
+
+export const MIGRATIONS_TABLE = "_pramen_migrations";
+
+/** One applied-migration ledger row. */
+export interface AppliedMigration {
+  id: string;
+  partition: string;
+  /** ISO-8601 UTC instant the migration committed. */
+  appliedAt: string;
+}
+
+/** 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: Driver): Promise<void> {
+  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: Driver, partition?: string): Promise<AppliedMigration[]> {
+  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: readonly DataMigration[],
+  partition: string,
+): readonly DataMigration[] {
+  return migrations.filter((m) => (m.partition ?? DEFAULT_PARTITION) === partition);
+}
+
+export interface RunMigrationsResult {
+  /** Ids applied by THIS run, in the order they committed. */
+  applied: string[];
+  /** Ids already in the ledger (a previous boot applied them). */
+  skipped: string[];
+}
+
+/** Lease timings. Defaults are deliberate, not arbitrary:
+ *
+ *  - `ttlMs` must EXCEED the slowest migration, because a lease that expires under a holder
+ *    still running is exactly the double-apply this whole mechanism prevents. 60s is above
+ *    anything that can finish inside a Worker's limits at all, and the docs already require
+ *    backfills to be bounded.
+ *  - `waitMs` bounds how long a runner blocks on someone else's live lease before failing
+ *    closed. Long enough for an ordinary backfill to land (so the waiter proceeds against
+ *    fully-migrated data), short enough not to hold a request open.
+ *  - `pollMs` is the re-check interval while waiting. */
+export interface LeaseOpts {
+  ttlMs: number;
+  waitMs: number;
+  pollMs: number;
+}
+
+export const DEFAULT_LEASE: LeaseOpts = { ttlMs: 60_000, waitMs: 5_000, pollMs: 100 };
+
+export interface RunMigrationsOpts {
+  /** The partition to run: only its migrations are selected, and each ledger row is keyed
+   * by it. OMIT it on the D1 store — see `runDataMigrations` for why that store runs every
+   * declared migration regardless of partition. */
+  partition?: string;
+  /** Build the privileged context for one migration. Called per migration with the
+   * partition its ledger row will be keyed under, so a caller can scope `db` accordingly. */
+  makeContext: (partition: string) => MigrationContext;
+  /** Override the lease timings (see `LeaseOpts`) — for tests, and for a deployment whose
+   * backfills legitimately run long. Absent ⇒ `DEFAULT_LEASE`. */
+  lease?: Partial<LeaseOpts>;
+}
+
+/** 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: Driver,
+  migrations: readonly DataMigration[],
+  opts: RunMigrationsOpts,
+): Promise<RunMigrationsResult> {
+  const applied: string[] = [];
+  const skipped: string[] = [];
+  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: string, partition: string): string => `${id}\u0000${partition}`;
+
+/** What one attempt at taking the ledger row found. */
+type ClaimOutcome = "claimed" | "applied" | "held";
+
+/** 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: Driver, id: string, partition: string, now: number, ttlMs: number): Promise<ClaimOutcome> {
+  const d = driver.dialect;
+  const t = d.id(MIGRATIONS_TABLE);
+  const params: CellValue[] = [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: Driver, id: string, partition: string, lease: LeaseOpts): Promise<"claimed" | "applied"> {
+  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: Driver, id: string, partition: string): Promise<void> {
+  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: Driver, id: string, partition: string): Promise<void> {
+  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: SchemaDef, migrations: readonly DataMigration[] | undefined): void {
+  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<string>();
+  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/src/runtime/mail.ts

@@ -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.
 
 import type { Kv } from "./kv";
 import type { EnvBag } from "../sdk/handlers";
@@ -83,6 +88,56 @@ export class CloudflareEmailAdapter implements MailAdapter {
   }
 }
 
+/** 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 implements MailAdapter {
+  constructor(
+    private readonly apiKey: string,
+    private readonly 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. */
+    private readonly apiBase: string = "https://api.mailgun.net",
+  ) {}
+
+  async send(message: MailMessage & { from: MailAddress }): Promise<void> {
+    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 implements MailAdapter {
@@ -109,23 +164,39 @@ export class MemoryMailAdapter implements MailAdapter {
 export class UnconfiguredMailAdapter implements MailAdapter {
   async send(): Promise<void> {
     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.",
+      "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: EnvBag, kv?: Kv): Mail {
   const binding = env.EMAIL as SendEmailBinding | undefined;
   const fromAddr = typeof env.MAIL_FROM === "string" && env.MAIL_FROM ? env.MAIL_FROM : undefined;
+  const str = (k: string): string | undefined =>
+    typeof env[k] === "string" && (env[k] as string) ? (env[k] as string) : 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/src/sdk/acl.ts

@@ -81,11 +81,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 function $now(): NowMarker {
   return { [NOW_MARKER]: true };
 }

package/src/sdk/handlers.ts

@@ -82,6 +82,49 @@ export interface BootstrapContext<S extends SchemaDef = SchemaDef> {
  * 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;