@pramen/server 0.0.59 → 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/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[]>;

package/dist/sdk/iso-timestamps.js

@@ -0,0 +1,119 @@
+// Rewriting timestamps written before `expr.now()` emitted ISO-8601.
+//
+// `expr.now()` used to emit `datetime('now')` — the `CURRENT_TIMESTAMP` space form,
+// `'2026-09-03 21:33:07'`. It now emits `'2026-09-03T21:33:07.222Z'`. Changing a column's
+// DEFAULT is a MODIFIER change, so `migrate()` rebuilds the table — and a rebuild copies
+// existing values through untouched. New rows would get the new shape and old rows would
+// keep the old one, in the same column.
+//
+// That is worse than either format alone, and the failure is narrower and nastier than
+// "the column is inconsistent". Both forms open with the same `YYYY-MM-DD`, so for values
+// on DIFFERENT dates the date prefix decides and ordering is still correct. It is values on
+// the SAME date that break: index 10 is ` ` (0x20) in the space form and `T` (0x54) in ISO,
+// so a same-day space-form value always sorts BEFORE a same-day ISO one whatever the
+// time-of-day — 23:00 in the old shape sorts below 01:00 in the new.
+//
+// Which makes the deploy window itself the blast radius: the rows written just before and
+// just after the change are exactly the same-day pairs that invert. And a `{ lte: $now() }`
+// policy is the sharp version, because `$now()` is ISO: a space-form value dated today
+// always compares as less than it, so a row scheduled for later TODAY reads as already
+// published until midnight. Nothing reports any of it.
+//
+// So the format change comes with a rewrite, and the rewrite is a DATA migration: it is
+// imperative, it must run exactly once, and it must fail closed. Declaring it is the app's
+// job — this builds it.
+import { DEFAULT_PARTITION, ISO_NOW_SQL, entitiesInPartition } from "./schema";
+/** The old default's SQL, for recognizing a column that carried it. */
+export const LEGACY_NOW_SQL = "datetime('now')";
+/**
+ * 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 function isoTimestampBackfill(opts = {}) {
+    const partition = opts.partition ?? DEFAULT_PARTITION;
+    return {
+        id: opts.id ?? "pramen:iso-timestamps",
+        partition,
+        async up(ctx) {
+            for (const [table, columns] of timestampColumns(ctx.schema, partition, opts.extraColumns)) {
+                for (const column of columns) {
+                    // A bulk UPDATE, not a walk: this runs inside `blockConcurrencyWhile` on a
+                    // tenant's first fetch, so a row-by-row rewrite of a large table is what stalls
+                    // that request and risks the DO's wall-clock limit.
+                    //
+                    // The predicate is deliberately exact rather than "does not look like ISO":
+                    // length 19 with a space at index 11 (SQLite's `substr` is 1-based) is the space
+                    // form and nothing else. A column holding some third format an app wrote by hand
+                    // is left alone, because guessing at it would be a silent rewrite of data this
+                    // migration does not understand.
+                    await ctx.driver.exec(`UPDATE ${q(table)} SET ${q(column)} = replace(${q(column)}, ' ', 'T') || '.000Z' ` +
+                        `WHERE ${q(column)} IS NOT NULL AND length(${q(column)}) = 19 AND substr(${q(column)}, 11, 1) = ' '`, []);
+                }
+            }
+        },
+    };
+}
+/**
+ * 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 function timestampColumns(schema, partition = DEFAULT_PARTITION, extra = {}) {
+    const out = new Map();
+    const inPartition = new Set(entitiesInPartition(schema, partition));
+    for (const table of inPartition) {
+        const fields = schema[table]?.fields;
+        if (!fields)
+            continue;
+        const cols = Object.entries(fields)
+            // Both spellings: a store written by an older build has the legacy default recorded
+            // in its own DDL, and `migrate()` may not have rebuilt the table yet when this runs
+            // (it does — migrations run after — but the check costs nothing and makes the set
+            // independent of that ordering).
+            .filter(([, f]) => f.defaultExpr === ISO_NOW_SQL || f.defaultExpr === LEGACY_NOW_SQL)
+            .map(([name]) => name);
+        if (cols.length > 0)
+            out.set(table, cols);
+    }
+    for (const [table, columns] of Object.entries(extra)) {
+        if (!inPartition.has(table))
+            continue;
+        const fields = schema[table]?.fields;
+        if (!fields)
+            continue;
+        const existing = out.get(table) ?? [];
+        for (const column of columns) {
+            if (fields[column] && !existing.includes(column))
+                existing.push(column);
+        }
+        if (existing.length > 0)
+            out.set(table, existing);
+    }
+    return out;
+}
+/** Double-quote an identifier for SQLite. Table and column names here come from the app's
+ * own schema, never from a request — but the SQL is built by concatenation, so they are
+ * quoted rather than trusted to be quote-free. */
+const q = (ident) => `"${ident.replace(/"/g, '""')}"`;

package/dist/sdk/schema.d.ts

@@ -242,9 +242,45 @@ export declare class ExprDefault {
     readonly sql: string;
     constructor(sql: string);
 }
-/** SQL-expression defaults for `defaultTo(field, expr.now())`. `now()` is the current
- * UTC timestamp as TEXT (`'YYYY-MM-DD HH:MM:SS'`, like `CURRENT_TIMESTAMP`) — pair it
- * with `t.text()`. `raw(sql)` is an escape hatch for any other SQLite default expression. */
+/**
+ * The SQL `expr.now()` emits: the current UTC instant as **ISO-8601 TEXT with
+ * milliseconds and a `Z`** — `'2026-09-03T21:33:07.222Z'`, byte-for-byte what
+ * `new Date().toISOString()` produces.
+ *
+ * Exported because three things have to agree on it and none of them can see the others:
+ * the DDL that writes the default, {@link isoTimestampBackfill} which rewrites rows
+ * written before this format, and the migration diff that decides a column's DEFAULT
+ * changed at all.
+ */
+export declare const ISO_NOW_SQL = "strftime('%Y-%m-%dT%H:%M:%fZ','now')";
+/**
+ * SQL-expression defaults for `defaultTo(field, expr.now())`.
+ *
+ * `now()` is the current UTC instant as ISO-8601 TEXT (`'2026-09-03T21:33:07.222Z'`) —
+ * pair it with `t.text()`.
+ *
+ * **It used to emit `datetime('now')`**, the `CURRENT_TIMESTAMP` space form
+ * (`'2026-09-03 21:33:07'`). That form is wrong for this codebase in two ways that both
+ * fail silently:
+ *
+ *   - It does not compare against `$now()`, which is an ISO string. Lexicographic TEXT
+ *     comparison is exact within one format and wrong across two: both open with
+ *     `YYYY-MM-DD`, so values on different dates still order correctly, but on the SAME
+ *     date index 10 decides — a space (0x20) always sorts below `T` (0x54), whatever the
+ *     time-of-day. So `{ publishedAt: { lte: $now() } }` over a space-form column matches
+ *     any row dated today, including one scheduled for later today. A time boundary that
+ *     silently does not hold, for a day at a time.
+ *   - It is second-resolution, so two writes in the same second are indistinguishable and
+ *     `ORDER BY createdAt` falls back to an arbitrary tiebreak. `%f` gives milliseconds.
+ *
+ * Changing it means a column's stored values change shape, so **existing rows must be
+ * rewritten** — a rebuild copies values through untouched and would leave the two formats
+ * mixed in one column, which is worse than either alone. {@link isoTimestampBackfill} is
+ * that rewrite; declare it in `app.migrations`.
+ *
+ * `raw(sql)` remains the escape hatch for any other SQLite default expression, including
+ * `expr.raw("datetime('now')")` if you deliberately want the old shape.
+ */
 export declare const expr: {
     now: () => ExprDefault;
     raw: (sql: string) => ExprDefault;

package/dist/sdk/schema.js

@@ -112,11 +112,47 @@ export class ExprDefault {
         this.sql = sql;
     }
 }
-/** SQL-expression defaults for `defaultTo(field, expr.now())`. `now()` is the current
- * UTC timestamp as TEXT (`'YYYY-MM-DD HH:MM:SS'`, like `CURRENT_TIMESTAMP`) — pair it
- * with `t.text()`. `raw(sql)` is an escape hatch for any other SQLite default expression. */
+/**
+ * The SQL `expr.now()` emits: the current UTC instant as **ISO-8601 TEXT with
+ * milliseconds and a `Z`** — `'2026-09-03T21:33:07.222Z'`, byte-for-byte what
+ * `new Date().toISOString()` produces.
+ *
+ * Exported because three things have to agree on it and none of them can see the others:
+ * the DDL that writes the default, {@link isoTimestampBackfill} which rewrites rows
+ * written before this format, and the migration diff that decides a column's DEFAULT
+ * changed at all.
+ */
+export const ISO_NOW_SQL = "strftime('%Y-%m-%dT%H:%M:%fZ','now')";
+/**
+ * SQL-expression defaults for `defaultTo(field, expr.now())`.
+ *
+ * `now()` is the current UTC instant as ISO-8601 TEXT (`'2026-09-03T21:33:07.222Z'`) —
+ * pair it with `t.text()`.
+ *
+ * **It used to emit `datetime('now')`**, the `CURRENT_TIMESTAMP` space form
+ * (`'2026-09-03 21:33:07'`). That form is wrong for this codebase in two ways that both
+ * fail silently:
+ *
+ *   - It does not compare against `$now()`, which is an ISO string. Lexicographic TEXT
+ *     comparison is exact within one format and wrong across two: both open with
+ *     `YYYY-MM-DD`, so values on different dates still order correctly, but on the SAME
+ *     date index 10 decides — a space (0x20) always sorts below `T` (0x54), whatever the
+ *     time-of-day. So `{ publishedAt: { lte: $now() } }` over a space-form column matches
+ *     any row dated today, including one scheduled for later today. A time boundary that
+ *     silently does not hold, for a day at a time.
+ *   - It is second-resolution, so two writes in the same second are indistinguishable and
+ *     `ORDER BY createdAt` falls back to an arbitrary tiebreak. `%f` gives milliseconds.
+ *
+ * Changing it means a column's stored values change shape, so **existing rows must be
+ * rewritten** — a rebuild copies values through untouched and would leave the two formats
+ * mixed in one column, which is worse than either alone. {@link isoTimestampBackfill} is
+ * that rewrite; declare it in `app.migrations`.
+ *
+ * `raw(sql)` remains the escape hatch for any other SQLite default expression, including
+ * `expr.raw("datetime('now')")` if you deliberately want the old shape.
+ */
 export const expr = {
-    now: () => new ExprDefault("datetime('now')"),
+    now: () => new ExprDefault(ISO_NOW_SQL),
     raw: (sql) => new ExprDefault(sql),
 };
 export function defaultTo(field, value) {