@pramen/server 0.0.59 → 0.0.60

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.59",
+  "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.

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";

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) };
 }