@pramen/server 0.0.58 → 0.0.60

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) {

package/dist/worker.js

@@ -6,6 +6,7 @@
 import { authorizeTenant, HmacStrategy, isAdmin, JwksStrategy, resolveIdentity } from "./auth";
 import { dispatch, tasksFacade, bindTasks } from "./runtime/dispatch";
 import { ensureOutbox, drainOutbox, listTasks } from "./runtime/outbox";
+import { appliedMigrations, runDataMigrations } from "./runtime/data-migrations";
 import { createMail } from "./runtime/mail";
 import { createQueue } from "./runtime/queue";
 import { dispatchQueueBatch } from "./runtime/queue-consumer";
@@ -169,6 +170,42 @@ export function makeWorker(app) {
             }
         }
     };
+    // The mirror of the DO's runDataMigrations() for the D1 store, run once per isolate after
+    // migration. It diverges in one deliberate way: it runs EVERY declared migration whatever
+    // partition it names, because D1 is ONE shared database with no partition split — every
+    // entity's table lives in it, so a migration declared for "audit" has real rows to touch
+    // here and would otherwise be permanently unrunnable on this store. Each is still recorded
+    // under its OWN declared partition key, so a ledger read is comparable across stores.
+    //
+    // Errors are NOT swallowed (unlike runBootstrapD1): the .catch in ensureD1Migrated clears
+    // `d1Ready`, so a failed migration fails this request and is retried on the next one —
+    // the same fail-closed contract as the DO path.
+    //
+    // ATOMICITY CAVEAT: D1's `transaction(fn)` is `fn()` (no interactive transactions), so
+    // here the claim and the work do NOT commit together. The runner claims the ledger row
+    // before running (which is what keeps two cold isolates from both applying the same
+    // backfill — `d1Ready` is per-isolate and there is no single writer) and releases it on a
+    // throw, so a failed migration leaves partial writes and re-runs. Write SQL that tolerates
+    // that (`WHERE col IS NULL`) when the D1 store is in play.
+    const runDataMigrationsD1 = async (driver) => {
+        const migrations = app.migrations;
+        if (!migrations?.length)
+            return;
+        const db = new Db(driver, { acl: d1Acl, identity: { roles: ["admin"] }, system: true, schema: app.schema, suppressTriggers: true }, app.schema);
+        await runDataMigrations(driver, migrations, {
+            // No `partition` — see the "runs every declared migration" note above.
+            makeContext: (partition) => ({ db, driver, schema: app.schema, partition }),
+        });
+    };
+    /** Partitions an admin route may address: the schema's, the default (always addressable),
+     * and any a data migration declares. Computed once — the app is static. */
+    let knownPartitionsCache;
+    const knownPartitions = () => {
+        if (!knownPartitionsCache) {
+            knownPartitionsCache = new Set([DEFAULT_PARTITION, ...partitionsOf(app.schema), ...(app.migrations ?? []).map((m) => m.partition ?? DEFAULT_PARTITION)]);
+        }
+        return knownPartitionsCache;
+    };
     let d1Ready;
     /** Run one handler against the D1 store, in the Worker. The request path and the
      * PRIVILEGED path (routes, which have no ctx.db) both come through here, so the two
@@ -214,6 +251,7 @@ export function makeWorker(app) {
     const ensureD1Migrated = (driver, allowDestructive) => {
         if (!d1Ready) {
             d1Ready = migrate(driver, app.schema, { allowDestructive })
+                .then(() => runDataMigrationsD1(driver)) // imperative, recorded backfills (fail closed)
                 .then(() => ensureOutbox(driver)) // the deferred-tasks table also lives in D1
                 .then(() => runBootstrapD1(driver)) // converge code-defined reference data
                 .then(() => undefined)
@@ -271,6 +309,26 @@ export function makeWorker(app) {
         await ensureD1Migrated(driver, env.PRAMEN_ALLOW_DESTRUCTIVE === "true");
         return listTasks(driver, { status, limit });
     };
+    /** Read the data-migration ledger straight from D1 in the Worker (there is no DO on this
+     * path), shaped exactly like the DO's /__migrations answer so the CLI can't tell them
+     * apart. The D1 ledger holds every partition's rows; filter to the one asked for.
+     *
+     * Strictly READ-ONLY: deliberately NOT ensureD1Migrated / ensureMigrationsTable. Booting
+     * the store here would apply every pending backfill as a side effect of asking about them,
+     * so `migrations status` could never report PENDING — which is the only question the
+     * command exists to answer. An absent ledger table is simply "none applied". */
+    const listD1Migrations = async (env, tenant, partition) => {
+        if (!env.DB)
+            throw new BadRequest("D1 store is not configured");
+        // The same COMMINGLING GUARD as every other D1 entry point: one shared database with no
+        // tenant column, so reporting it as some specific tenant's ledger requires the opt-in.
+        if (tenant !== "main" && env.PRAMEN_D1_ALLOW_MULTITENANT !== "true") {
+            throw new Forbidden(`D1 store for tenant '${tenant}' (shared D1 has no tenant isolation — set PRAMEN_D1_ALLOW_MULTITENANT=true to allow)`);
+        }
+        const driver = new D1Driver(env.DB, { start: "first-primary" });
+        const rows = await appliedMigrations(driver, partition).catch(() => []);
+        return { partition, applied: rows.map((r) => ({ id: r.id, appliedAt: r.appliedAt })) };
+    };
     return {
         async fetch(request, env, ctx) {
             const url = new URL(request.url);
@@ -397,6 +455,35 @@ export function makeWorker(app) {
                 const res = await stub.fetch(new Request("https://do/__schema", { headers: { "x-pramen-tenant": tenant, "x-pramen-partition": partition } }));
                 return withCors(res, cors);
             }
+            // --- admin: which data migrations a tenant has applied. The fleet-wide "is it safe to
+            // prune this id?" signal — a cold tenant is unmigrated until touched, so nothing else
+            // can answer it. `x-pramen-store: d1` reads the Worker's shared ledger instead. ---
+            if (url.pathname === "/admin/migrations") {
+                if (!isAdmin(identity))
+                    return withCors(forbidden("migrations"), cors);
+                const partition = url.searchParams.get("partition") || DEFAULT_PARTITION;
+                const tenant = url.searchParams.get("tenant") ?? "main";
+                // `partition` is caller-supplied and reaches partitionStubFor, which INSTANTIATES a
+                // DO — the same reason /live validates it: without this an admin typo mints a junk DO
+                // and a permanent registry key for a partition nothing lives in. A migration may
+                // declare a partition of its own, so accept those too.
+                if (!knownPartitions().has(partition))
+                    return withCors(badRequest(`unknown partition '${partition}'`), cors);
+                try {
+                    if (request.headers.get("x-pramen-store") === "d1") {
+                        return withCors(json({ ok: true, result: await listD1Migrations(env, tenant, partition) }), cors);
+                    }
+                    const stub = partitionStubFor(env, tenant, partition);
+                    const res = await stub.fetch(new Request("https://do/__migrations", { headers: { "x-pramen-tenant": tenant, "x-pramen-partition": partition } }));
+                    return withCors(res, cors);
+                }
+                catch (err) {
+                    // The DO branch throws a plain Error on a D1-ONLY deployment (no PRAMEN binding).
+                    // Uncaught that is an opaque 500; surfaced, it's the actionable "pin the D1 store".
+                    const { status, body } = toResponse(err);
+                    return withCors(json(body, status), cors);
+                }
+            }
             // --- admin: generic data ops over a tenant's tables (browse/edit any row).
             // Body: { tenant, table, op: list|get|create|update|delete|count, ... }. Runs
             // in the DO under SYSTEM scope (ACL bypassed) — gated to admins here. ---
@@ -475,7 +562,7 @@ export function makeWorker(app) {
                     "Header X-Pramen-Tenant selects the store (default: main). " +
                     "Admin (optional partition selects the partition DO, default: " + DEFAULT_PARTITION + "): " +
                     "GET /tenants, POST /admin/recover {tenant,timestamp,partition?}, GET /admin/schema?tenant=&partition=, " +
-                    "POST /admin/data {tenant,table,op,partition?}.\n", { headers: { "content-type": "text/plain" } });
+                    "GET /admin/migrations?tenant=&partition=, POST /admin/data {tenant,table,op,partition?}.\n", { headers: { "content-type": "text/plain" } });
             }
             // Authorize the tenant against the identity before reaching the DO, so a
             // caller can't address (or register) tenants they have no claim to.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/server",
-  "version": "0.0.58",
+  "version": "0.0.60",
   "description": "pramen server runtime \u2014 schema, ACL, ORM, live queries, files, and the createPramen(app) factory for Cloudflare Workers + Durable Objects.",
   "license": "MIT",
   "repository": {

package/src/cli.ts

@@ -10,6 +10,8 @@
 //   pramen schema snapshot            save the current schema to .pramen/schema.json
 //   pramen schema diff                compare the schema to the snapshot (safe vs unsafe changes)
 //   pramen schema status [--tenant t] [--url u] [--token jwt]   compare a deployed tenant to the schema
+//   pramen migrations list            declared data-migration ids, in order
+//   pramen migrations status          applied vs pending, per tenant + partition
 //   pramen token <sub> [roles...] [--tenant a,b]                mint a dev JWT
 //
 // The bin uses a `bun` shebang: the `schema *` commands import your app module (a .ts
@@ -22,7 +24,9 @@ import { dirname, resolve } from "node:path";
 import { createTableSql } from "./runtime/ddl";
 import { schemaHash } from "./runtime/migrate";
 import { diffSchemaFingerprint, schemaFingerprint, type SchemaFingerprint } from "./runtime/schema-diff";
-import { entitiesInPartition, partitionsOf, type SchemaDef } from "./sdk/schema";
+import { DEFAULT_PARTITION, entitiesInPartition, partitionsOf, type SchemaDef } from "./sdk/schema";
+import { migrationsForPartition } from "./runtime/data-migrations";
+import type { DataMigration } from "./sdk/handlers";
 import { signDevToken } from "./runtime/dev-token";
 
 /** The dev JWT claims `pramen token` mints. See `runtime/dev-token.ts` for the signer. */
@@ -57,14 +61,21 @@ function fail(msg: string): never {
   process.exit(1);
 }
 
-async function loadApp(): Promise<{ schema: SchemaDef }> {
+/** The slice of an app module the CLI needs: the schema, plus the declared data
+ * migrations (`migrations list`/`status` read them; every other command ignores them). */
+interface LoadedApp {
+  schema: SchemaDef;
+  migrations?: readonly DataMigration[];
+}
+
+async function loadApp(): Promise<LoadedApp> {
   const explicit = flag("app");
   const candidates = explicit ? [explicit] : ["./app.ts", "./example/app.ts"];
   for (const c of candidates) {
     const p = resolve(process.cwd(), c);
     if (existsSync(p)) {
-      const mod = (await import(p)) as { app?: { schema?: SchemaDef } };
-      if (mod.app?.schema) return mod.app as { schema: SchemaDef };
+      const mod = (await import(p)) as { app?: Partial<LoadedApp> };
+      if (mod.app?.schema) return { schema: mod.app.schema, migrations: mod.app.migrations };
       fail(`${c} does not export { app }`);
     }
   }
@@ -83,6 +94,9 @@ Usage: pramen <command>
   schema diff               compare the schema to the snapshot (safe vs unsafe)
   schema status             compare a deployed tenant's schema to the local schema
                             [--tenant t] [--url u] [--token jwt]
+  migrations list           declared data migration ids, in order (id + partition)
+  migrations status         applied vs pending data migrations for a deployed tenant
+                            [--tenant t] [--all-tenants] [--store d1] [--url u] [--token jwt]
   token <sub> [roles...]    mint a dev JWT [--tenant a,b]
 
 Flags: --app <path> to point at your app module (default ./app.ts or ./example/app.ts).`;
@@ -200,6 +214,111 @@ async function schemaCmd(sub: string | undefined): Promise<void> {
   console.log(HELP);
 }
 
+/** One (tenant, partition) the ledger is read for. `--all-tenants` fans out over the
+ * registry's real pairs; otherwise the schema's partitions for one tenant. */
+interface MigrationTarget {
+  tenant: string;
+  partition: string;
+}
+
+/** GET the applied-migration ledger for one (tenant, partition). Exits non-zero rather
+ * than reporting a partial fleet — "not answered" must never read as "not applied". */
+async function fetchApplied(
+  url: string,
+  token: string,
+  target: MigrationTarget,
+  store: string | undefined,
+): Promise<{ id: string; appliedAt: string }[]> {
+  const qs = target.partition === DEFAULT_PARTITION ? "" : `&partition=${encodeURIComponent(target.partition)}`;
+  const headers = new Headers({ authorization: `Bearer ${token}` });
+  // The ledger lives in the Worker's shared D1 on that store — there is no DO to ask, and
+  // without this header the request routes to a DO binding a D1-only deploy doesn't have.
+  if (store === "d1") headers.set("x-pramen-store", "d1");
+  const res = await fetch(`${url}/admin/migrations?tenant=${encodeURIComponent(target.tenant)}${qs}`, {
+    headers,
+  }).catch((e: Error) => fail(`migrations status: cannot reach ${url} (${e.message})`));
+  const body = (await res.json().catch(() => ({}))) as {
+    ok?: boolean;
+    result?: { partition: string; applied: { id: string; appliedAt: string }[] };
+    error?: string;
+  };
+  if (!res.ok || !body.ok || !body.result) {
+    fail(`migrations status failed (tenant ${target.tenant}, partition ${target.partition}): ${body.error ?? res.status}`);
+  }
+  return body.result!.applied;
+}
+
+async function migrationsCmd(sub: string | undefined): Promise<void> {
+  if (sub === "list") {
+    const { migrations } = await loadApp();
+    if (!migrations?.length) {
+      console.log("no migrations declared.");
+      return;
+    }
+    for (const m of migrations) console.log(`${m.id}  (partition: ${m.partition ?? DEFAULT_PARTITION})`);
+    return;
+  }
+  if (sub === "status") {
+    const { schema, migrations } = await loadApp();
+    const declared = migrations ?? [];
+    const url = flag("url") ?? "http://localhost:8787";
+    const token = flag("token") ?? (await sign({ sub: "cli", roles: ["admin"] }));
+    const store = flag("store");
+    if (store !== undefined && store !== "d1" && store !== "do") fail(`migrations status: --store must be "do" or "d1"`);
+
+    // --all-tenants asks the registry which (tenant, partition) DOs actually exist — the
+    // only way to answer "is it safe to prune this id?", since a tenant nobody has touched
+    // since the migration shipped is still unmigrated and no local artifact knows that.
+    let targets: MigrationTarget[];
+    if (argv.includes("--all-tenants")) {
+      const res = await fetch(`${url}/tenants`, { headers: { authorization: `Bearer ${token}` } }).catch(
+        (e: Error) => fail(`migrations status: cannot reach ${url} (${e.message})`),
+      );
+      const body = (await res.json().catch(() => ({}))) as { ok?: boolean; result?: MigrationTarget[]; error?: string };
+      if (!res.ok || !body.ok || !body.result) fail(`migrations status: /tenants failed: ${body.error ?? res.status}`);
+      targets = body.result!;
+    } else {
+      const tenant = flag("tenant") ?? "main";
+      // Union the schema's partitions with the ones the migrations themselves declare.
+      // partitionsOf() only returns partitions an ENTITY lives in, so an app whose every
+      // entity is partitioned would drop the default partition from the report — and a
+      // default-partition migration would silently never be listed, in the one command
+      // whose answer gates deleting it.
+      const declaredIn = declared.map((m) => m.partition ?? DEFAULT_PARTITION);
+      targets = [...new Set([...partitionsOf(schema), ...declaredIn])].map((partition) => ({ tenant, partition }));
+    }
+
+    for (const target of targets) {
+      console.log(`\ntenant: ${target.tenant}   partition: ${target.partition}`);
+      const applied = await fetchApplied(url, token, target, store);
+      const appliedAt = new Map(applied.map((a) => [a.id, a.appliedAt]));
+      const forHere = migrationsForPartition(declared, target.partition);
+      let pending = 0;
+      for (const m of forHere) {
+        const at = appliedAt.get(m.id);
+        if (at) console.log(`  ✓ ${m.id}  (applied ${at})`);
+        else {
+          console.log(`  • ${m.id} PENDING`);
+          pending++;
+        }
+      }
+      // A ledger row with no declaration left in the codebase — the pruning question in
+      // reverse. Harmless (it stays applied), but it means this deploy no longer describes
+      // what ran, so a fresh tenant and this one are NOT converging on the same history.
+      const declaredIds = new Set(forHere.map((m) => m.id));
+      for (const a of applied) if (!declaredIds.has(a.id)) console.log(`  ? ${a.id} applied but NOT DECLARED`);
+      console.log(`  ${forHere.length - pending} applied, ${pending} pending`);
+    }
+    console.log(
+      "\nA migration is only safe to DELETE once EVERY live tenant reports it applied — the same trap as\n" +
+        "`renamedFrom`: migration is lazy and per-DO, so a tenant nobody has touched is still unmigrated\n" +
+        "and would silently skip the id if it were gone. Check with --all-tenants.",
+    );
+    return;
+  }
+  console.log(HELP);
+}
+
 async function tokenCmd(args: string[]): Promise<void> {
   const pos = positionals(args);
   const sub = pos[0];
@@ -310,6 +429,8 @@ async function main(): Promise<void> {
       return initCmd(argv.slice(1));
     case "schema":
       return schemaCmd(argv[1]);
+    case "migrations":
+      return migrationsCmd(argv[1]);
     case "token":
       return tokenCmd(argv.slice(1));
     default:

package/src/durable-object.ts

@@ -21,6 +21,7 @@ import { dispatch, tasksFacade, bindTasks } from "./runtime/dispatch";
 import { createMail } from "./runtime/mail";
 import { createQueue } from "./runtime/queue";
 import { ensureOutbox, drainOutbox, listTasks } from "./runtime/outbox";
+import { appliedMigrations, runDataMigrations as runPendingDataMigrations } from "./runtime/data-migrations";
 import { Db } from "./runtime/db";
 import { digest } from "./runtime/digest";
 import { compileAcl, type AclContext, type CompiledAcl } from "./runtime/acl";
@@ -148,12 +149,38 @@ export class PramenDOBase extends DurableObject<DoEnv> {
       await this.driver.transaction(() =>
         migrate(this.driver, this.app.schema, { allowDestructive, partition }).then(() => {}),
       );
+      await this.runDataMigrations(); // imperative, recorded backfills for THIS partition
       await ensureOutbox(this.driver); // the deferred-tasks table (internal, all partitions)
       await this.runBootstrap(); // converge code-defined reference data (default partition only)
       this.migrated = true;
     });
   }
 
+  // Run this partition's pending app.migrations once, right after migrate() (so a backfill
+  // sees the column ADD COLUMN just created) and before bootstrap. Unlike runBootstrap this
+  // is NOT default-partition-only: a partition's rows live in ITS DO, so each partition-DO
+  // runs its own partition's migrations against its own tables.
+  //
+  // It deliberately does NOT swallow errors, which is the one place it diverges from
+  // runBootstrap. A bootstrap reconciler is idempotent and retried every boot, so logging a
+  // failure and carrying on is safe; a data migration is a ONE-SHOT transformation of user
+  // rows, and swallowing a half-finished backfill would leave the store silently corrupt
+  // AND (via the ledger row it never wrote) look unmigrated forever. Failing closed brings
+  // the tenant's first fetch down instead, and the migration retries on the next one.
+  private async runDataMigrations(): Promise<void> {
+    const migrations = this.app.migrations;
+    if (!migrations?.length) return;
+    const db = new Db(
+      this.driver,
+      { acl: this.acl, identity: { roles: ["admin"] }, system: true, partition: this.partition, schema: this.app.schema, suppressTriggers: true },
+      this.app.schema,
+    );
+    await runPendingDataMigrations(this.driver, migrations, {
+      partition: this.partition,
+      makeContext: (partition) => ({ db, driver: this.driver, schema: this.app.schema, partition }),
+    });
+  }
+
   // Run app.bootstrap() once per DO lifetime, right after migration and inside the same
   // blockConcurrencyWhile block, so the first request sees a converged store and two
   // concurrent first fetches can't double-run it. Default partition ONLY: reference data
@@ -187,6 +214,14 @@ export class PramenDOBase extends DurableObject<DoEnv> {
     const partitionHeader = request.headers.get("x-pramen-partition");
     if (partitionHeader) this.partition = partitionHeader;
 
+    // READ-ONLY PROBE, answered before the boot. Everything below this line migrates:
+    // ensureMigrated() runs migrate(), the data migrations and bootstrap. Answering the
+    // ledger after that would make `pramen migrations status` apply every pending backfill
+    // as a side effect of ASKING — it could never report PENDING, and `--all-tenants`
+    // (advertised as the read-only "is it safe to prune?" check) would silently migrate the
+    // whole fleet. Reads no table it might have to create; see handleMigrations.
+    if (new URL(request.url).pathname === "/__migrations") return this.handleMigrations();
+
     await this.ensureMigrated();
     await this.ensureRegistered(request);
     // Persist (tenant, partition) once per instance so a cold alarm can rebuild the
@@ -583,6 +618,24 @@ export class PramenDOBase extends DurableObject<DoEnv> {
     return Response.json({ ok: true, result: { hash: byKey.get(hashKey) ?? null, tables } });
   }
 
+  // Introspection: which data migrations this partition has applied (admin-gated at the
+  // Worker). Powers the CLI's `migrations status` — the fleet-wide "is it safe to prune this
+  // id yet?" answer, which nothing else can give: a tenant nobody has touched since the
+  // migration shipped is still unmigrated, and the schema hash says nothing about backfills.
+  // Ensure the ledger exists first so a DO that has never applied one answers with [] rather
+  // than a missing-table error.
+  private async handleMigrations(): Promise<Response> {
+    // Strictly read-only — NOT ensureMigrationsTable(). A DO that has never applied a
+    // migration has no ledger table, and CREATE-ing one here would make the probe a write
+    // (and would boot an otherwise-untouched tenant's store just to answer a question about
+    // it). An absent table is simply "none applied".
+    const rows = await appliedMigrations(this.driver, this.partition).catch(() => []);
+    return Response.json({
+      ok: true,
+      result: { partition: this.partition, applied: rows.map((r) => ({ id: r.id, appliedAt: r.appliedAt })) },
+    });
+  }
+
   // Generic admin data ops (admin-gated at the Worker). Runs through a SYSTEM-mode
   // Db, so ACL is bypassed — admin can browse/edit any row of any table — while the
   // json/fileRef codec, transactions, and live-query broadcast still apply.