@pramen/server 0.0.22 → 0.0.24

package/dist/durable-object.d.ts

@@ -45,6 +45,7 @@ export declare class PramenDOBase extends DurableObject<DoEnv> {
     private readonly subsBySocket;
     constructor(ctx: DurableObjectState, env: DoEnv, app: PramenApp);
     private ensureMigrated;
+    private runBootstrap;
     fetch(request: Request): Promise<Response>;
     /** Arm the drain alarm soon after a mutation enqueued task(s). setAlarm replaces any
      * pending alarm; a near-future time batches a burst of enqueues into one drain. */

package/dist/durable-object.js

@@ -95,9 +95,32 @@ export class PramenDOBase extends DurableObject {
                 return; // a concurrent first request already migrated
             await this.driver.transaction(() => migrate(this.driver, this.app.schema, { allowDestructive, partition }).then(() => { }));
             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 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
+    // (content types, roles, …) lives in the default partition, and a non-default DO doesn't
+    // own those tables (a write would trip assertInPartition). A failing reconciler is logged
+    // and swallowed — unlike migrate(), it must never brick a tenant's boot; it retries next
+    // boot. Uses a SYSTEM-scoped Db (ACL bypassed) with triggers suppressed (a boot-time seed
+    // shouldn't fan out reactive side-effects).
+    async runBootstrap() {
+        const fns = this.app.bootstrap;
+        if (!fns?.length || this.partition !== DEFAULT_PARTITION)
+            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);
+        for (const fn of fns) {
+            try {
+                await this.driver.transaction(() => Promise.resolve(fn({ db, driver: this.driver, schema: this.app.schema, partition: this.partition })));
+            }
+            catch (e) {
+                console.error(`[pramen] bootstrap failed (partition=${this.partition}):`, e);
+            }
+        }
+    }
     async fetch(request) {
         const tenantHeader = request.headers.get("x-pramen-tenant");
         if (tenantHeader)

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { isValidUuid } from "./sdk/uuid";
 export type { DefaultValue, FieldType, FieldDef, EntityFields, EntityDef, SchemaDef, RelationDef, RelationDefs, BelongsToDef, HasManyDef, } from "./sdk/schema";
 export { createApp } from "./sdk/app";
 export { query, mutation, authorizeHandler } from "./sdk/handlers";
-export type { Handler, HandlerContext, HandlerKind, HandlerMap, HandlerOpts, HandlerAuth, Tasks, TaskHandler, AppTaskMap } from "./sdk/handlers";
+export type { Handler, HandlerContext, HandlerKind, HandlerMap, HandlerOpts, HandlerAuth, Tasks, TaskHandler, AppTaskMap, BootstrapContext, BootstrapFn } from "./sdk/handlers";
 export { $identity, $input, allow, deny, policy, resolve, role, isAllow, isDeny, isResolver, isIdentityMarker, isInputMarker } from "./sdk/acl";
 export type { Action, Identity, IdentityMarker, InputMarker, Policy, PolicyRule, PolicyRules, Role, Validator, WhereRule, ConditionalFields, FieldsFn, RelationAclRule, SetValue, ResolverFn, ResolverContext, ResolverDb, } from "./sdk/acl";
 export type { Cell, FieldsOf, InferInsert, InferRow, InferUpdate, JsonValue, ProjectedRow, RelationsOf, RelationsResult, WhereClause, WhereInput, WhereOps, } from "./sdk/infer";

package/dist/pramen.d.ts

@@ -1,7 +1,7 @@
 import { type Env } from "./worker";
 import { pramenDO, type DoEnv } from "./durable-object";
 import { type SchemaDef } from "./sdk/schema";
-import type { AppTaskMap, HandlerMap } from "./sdk/handlers";
+import type { AppTaskMap, HandlerMap, BootstrapFn } from "./sdk/handlers";
 import type { AppQueueMap, QueueBatch } from "./runtime/queue-consumer";
 import type { Role } from "./sdk/acl";
 /** Injected into a public route's handler — forward a privileged mutation into the
@@ -41,6 +41,10 @@ export interface PramenApp {
      * `ctx.queue.send(...)`. Dispatched by `createPramen(app).queue` (a consumer is
      * Worker-level: no `ctx.db`, reach a tenant via `ctx.callPrivileged`). */
     queues?: AppQueueMap;
+    /** Idempotent reconcilers run once after schema migration on each boot — converge
+     * code-defined reference data into the store (see `BootstrapFn`). Each runs with a
+     * privileged system Db; failures are logged, never fatal. */
+    bootstrap?: readonly BootstrapFn[];
 }
 export type { Env, DoEnv };
 /** Build the deployable pair for an app. `scheduled` is a Cron Trigger entry that

package/dist/sdk/handlers.d.ts

@@ -1,4 +1,5 @@
 import type { Db } from "../runtime/db";
+import type { Driver } from "../runtime/driver";
 import type { Kv } from "../runtime/kv";
 import type { Mail } from "../runtime/mail";
 import type { Queue } from "../runtime/queue";
@@ -39,6 +40,26 @@ export interface HandlerContext<S extends SchemaDef = SchemaDef> {
      * Declare queues in oblaka.ts; consume them via `app.queues`. */
     readonly queue: Queue;
 }
+/** Context handed to each `app.bootstrap` function. A privileged, SYSTEM-scoped `Db` (ACL
+ * bypassed) plus the raw driver, available once schema migration has run on boot. Use it to
+ * reconcile CODE-DEFINED reference data — content types, block types, roles, feature flags —
+ * into the store, so a fresh / reprovisioned database converges to what the repo declares
+ * instead of depending on rows someone created by hand. */
+export interface BootstrapContext<S extends SchemaDef = SchemaDef> {
+    /** System-scoped Db (ACL bypassed), scoped to `partition`. */
+    readonly db: Db<S>;
+    /** Raw driver — for `driver.transaction(...)` or bespoke SQL. */
+    readonly driver: Driver;
+    readonly schema: S;
+    /** The partition being booted. On the DO path bootstrap runs ONLY for the default
+     * partition (reference data lives there); on the D1 path it is always the default. */
+    readonly partition: string;
+}
+/** An idempotent reconcile run once after `migrate()` on each boot (a DO's first fetch, or a
+ * Worker/D1 isolate init). It MUST be safe to run repeatedly — upsert by a stable key, never
+ * 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>;
 /** 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/worker.js

@@ -129,11 +129,30 @@ export function makeWorker(app) {
     // its own). Schema migration over D1 runs once per isolate (and short-circuits on a
     // stored schema hash thereafter); a failed run is not cached.
     const d1Acl = compileAcl(app.acl ?? []);
+    // Converge code-defined reference data on the D1 path — the mirror of the DO's
+    // runBootstrap(), run once per isolate after migration. D1 is a single shared store (no
+    // partition split), so every reconciler runs under the default partition. SYSTEM-scoped
+    // Db (ACL bypassed), triggers suppressed; a failing reconciler is logged, never fatal.
+    const runBootstrapD1 = async (driver) => {
+        const fns = app.bootstrap;
+        if (!fns?.length)
+            return;
+        const db = new Db(driver, { acl: d1Acl, identity: { roles: ["admin"] }, system: true, schema: app.schema, suppressTriggers: true }, app.schema);
+        for (const fn of fns) {
+            try {
+                await driver.transaction(() => Promise.resolve(fn({ db, driver, schema: app.schema, partition: DEFAULT_PARTITION })));
+            }
+            catch (e) {
+                console.error("[pramen] bootstrap failed (d1):", e);
+            }
+        }
+    };
     let d1Ready;
     const ensureD1Migrated = (driver, allowDestructive) => {
         if (!d1Ready) {
             d1Ready = migrate(driver, app.schema, { allowDestructive })
                 .then(() => ensureOutbox(driver)) // the deferred-tasks table also lives in D1
+                .then(() => runBootstrapD1(driver)) // converge code-defined reference data
                 .then(() => undefined)
                 .catch((e) => {
                 d1Ready = undefined;

package/package.json

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

package/src/durable-object.ts

@@ -133,10 +133,36 @@ export class PramenDOBase extends DurableObject<DoEnv> {
         migrate(this.driver, this.app.schema, { allowDestructive, partition }).then(() => {}),
       );
       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 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
+  // (content types, roles, …) lives in the default partition, and a non-default DO doesn't
+  // own those tables (a write would trip assertInPartition). A failing reconciler is logged
+  // and swallowed — unlike migrate(), it must never brick a tenant's boot; it retries next
+  // boot. Uses a SYSTEM-scoped Db (ACL bypassed) with triggers suppressed (a boot-time seed
+  // shouldn't fan out reactive side-effects).
+  private async runBootstrap(): Promise<void> {
+    const fns = this.app.bootstrap;
+    if (!fns?.length || this.partition !== DEFAULT_PARTITION) 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,
+    );
+    for (const fn of fns) {
+      try {
+        await this.driver.transaction(() => Promise.resolve(fn({ db, driver: this.driver, schema: this.app.schema, partition: this.partition })));
+      } catch (e) {
+        console.error(`[pramen] bootstrap failed (partition=${this.partition}):`, e);
+      }
+    }
+  }
+
   override async fetch(request: Request): Promise<Response> {
     const tenantHeader = request.headers.get("x-pramen-tenant");
     if (tenantHeader) this.tenant = tenantHeader;

package/src/index.ts

@@ -27,7 +27,7 @@ export type {
 // --- app + handlers ---
 export { createApp } from "./sdk/app";
 export { query, mutation, authorizeHandler } from "./sdk/handlers";
-export type { Handler, HandlerContext, HandlerKind, HandlerMap, HandlerOpts, HandlerAuth, Tasks, TaskHandler, AppTaskMap } from "./sdk/handlers";
+export type { Handler, HandlerContext, HandlerKind, HandlerMap, HandlerOpts, HandlerAuth, Tasks, TaskHandler, AppTaskMap, BootstrapContext, BootstrapFn } from "./sdk/handlers";
 
 // --- ACL ---
 export { $identity, $input, allow, deny, policy, resolve, role, isAllow, isDeny, isResolver, isIdentityMarker, isInputMarker } from "./sdk/acl";

package/src/pramen.ts

@@ -15,7 +15,7 @@
 import { makeWorker, type Env } from "./worker";
 import { pramenDO, type DoEnv } from "./durable-object";
 import { validateTriggerTasks, type SchemaDef } from "./sdk/schema";
-import type { AppTaskMap, HandlerMap } from "./sdk/handlers";
+import type { AppTaskMap, HandlerMap, BootstrapFn } from "./sdk/handlers";
 import type { AppQueueMap, QueueBatch } from "./runtime/queue-consumer";
 import type { Role } from "./sdk/acl";
 
@@ -53,6 +53,10 @@ export interface PramenApp {
    * `ctx.queue.send(...)`. Dispatched by `createPramen(app).queue` (a consumer is
    * Worker-level: no `ctx.db`, reach a tenant via `ctx.callPrivileged`). */
   queues?: AppQueueMap;
+  /** Idempotent reconcilers run once after schema migration on each boot — converge
+   * code-defined reference data into the store (see `BootstrapFn`). Each runs with a
+   * privileged system Db; failures are logged, never fatal. */
+  bootstrap?: readonly BootstrapFn[];
 }
 
 export type { Env, DoEnv };

package/src/sdk/handlers.ts

@@ -3,6 +3,7 @@
 // rolls back on throw (see runtime/dispatch.ts).
 
 import type { Db } from "../runtime/db";
+import type { Driver } from "../runtime/driver";
 import type { Kv } from "../runtime/kv";
 import type { Mail } from "../runtime/mail";
 import type { Queue } from "../runtime/queue";
@@ -45,6 +46,28 @@ export interface HandlerContext<S extends SchemaDef = SchemaDef> {
   readonly queue: Queue;
 }
 
+/** Context handed to each `app.bootstrap` function. A privileged, SYSTEM-scoped `Db` (ACL
+ * bypassed) plus the raw driver, available once schema migration has run on boot. Use it to
+ * reconcile CODE-DEFINED reference data — content types, block types, roles, feature flags —
+ * into the store, so a fresh / reprovisioned database converges to what the repo declares
+ * instead of depending on rows someone created by hand. */
+export interface BootstrapContext<S extends SchemaDef = SchemaDef> {
+  /** System-scoped Db (ACL bypassed), scoped to `partition`. */
+  readonly db: Db<S>;
+  /** Raw driver — for `driver.transaction(...)` or bespoke SQL. */
+  readonly driver: Driver;
+  readonly schema: S;
+  /** The partition being booted. On the DO path bootstrap runs ONLY for the default
+   * partition (reference data lives there); on the D1 path it is always the default. */
+  readonly partition: string;
+}
+
+/** An idempotent reconcile run once after `migrate()` on each boot (a DO's first fetch, or a
+ * Worker/D1 isolate init). It MUST be safe to run repeatedly — upsert by a stable key, never
+ * 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>;
+
 /** 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/src/worker.ts

@@ -191,11 +191,30 @@ export function makeWorker(app: PramenApp) {
   // its own). Schema migration over D1 runs once per isolate (and short-circuits on a
   // stored schema hash thereafter); a failed run is not cached.
   const d1Acl = compileAcl(app.acl ?? []);
+
+  // Converge code-defined reference data on the D1 path — the mirror of the DO's
+  // runBootstrap(), run once per isolate after migration. D1 is a single shared store (no
+  // partition split), so every reconciler runs under the default partition. SYSTEM-scoped
+  // Db (ACL bypassed), triggers suppressed; a failing reconciler is logged, never fatal.
+  const runBootstrapD1 = async (driver: Driver): Promise<void> => {
+    const fns = app.bootstrap;
+    if (!fns?.length) return;
+    const db = new Db(driver, { acl: d1Acl, identity: { roles: ["admin"] }, system: true, schema: app.schema, suppressTriggers: true }, app.schema);
+    for (const fn of fns) {
+      try {
+        await driver.transaction(() => Promise.resolve(fn({ db, driver, schema: app.schema, partition: DEFAULT_PARTITION })));
+      } catch (e) {
+        console.error("[pramen] bootstrap failed (d1):", e);
+      }
+    }
+  };
+
   let d1Ready: Promise<void> | undefined;
   const ensureD1Migrated = (driver: Driver, allowDestructive: boolean): Promise<void> => {
     if (!d1Ready) {
       d1Ready = migrate(driver, app.schema, { allowDestructive })
         .then(() => ensureOutbox(driver)) // the deferred-tasks table also lives in D1
+        .then(() => runBootstrapD1(driver)) // converge code-defined reference data
         .then(() => undefined)
         .catch((e) => {
           d1Ready = undefined;