@pramen/server 0.0.3 → 0.0.4

package/dist/durable-object.d.ts

@@ -22,8 +22,16 @@ export declare class PramenDOBase extends DurableObject<DoEnv> {
     /** Tenant this DO serves (one per idFromName). Learned from the Worker-forwarded
      * x-pramen-tenant header; defaults to "main". */
     private tenant;
+    /** Partition this DO serves (one per idFromName(partitionDoName)). Learned from the
+     * Worker-forwarded x-pramen-partition header on the first fetch; defaults to the
+     * default partition (a single-partition app, or a stray request with no header). */
+    private partition;
+    /** Boot migration runs on the FIRST fetch (once the partition is known), not in the
+     * constructor — see `ensureMigrated`. Guards against re-running. */
+    private migrated;
     private files?;
     constructor(ctx: DurableObjectState, env: DoEnv, app: PramenApp);
+    private ensureMigrated;
     fetch(request: Request): Promise<Response>;
     webSocketMessage(ws: WebSocket, raw: string | ArrayBuffer): Promise<void>;
     webSocketClose(ws: WebSocket): Promise<void>;

package/dist/durable-object.js

@@ -23,6 +23,8 @@ import { compileAcl } from "./runtime/acl";
 import { DoSqliteDriver } from "./runtime/driver";
 import { BadRequest, toResponse, toWsError } from "./runtime/errors";
 import { Kv } from "./runtime/kv";
+import { registryKey } from "./runtime/registry";
+import { DEFAULT_PARTITION } from "./sdk/schema";
 import { createFiles, R2Adapter } from "./runtime/storage";
 /** Per-socket subscription cap — bounds memory and per-mutation re-run cost. */
 const MAX_SUBSCRIPTIONS = 64;
@@ -35,6 +37,13 @@ export class PramenDOBase extends DurableObject {
     /** Tenant this DO serves (one per idFromName). Learned from the Worker-forwarded
      * x-pramen-tenant header; defaults to "main". */
     tenant = "main";
+    /** Partition this DO serves (one per idFromName(partitionDoName)). Learned from the
+     * Worker-forwarded x-pramen-partition header on the first fetch; defaults to the
+     * default partition (a single-partition app, or a stray request with no header). */
+    partition = DEFAULT_PARTITION;
+    /** Boot migration runs on the FIRST fetch (once the partition is known), not in the
+     * constructor — see `ensureMigrated`. Guards against re-running. */
+    migrated = false;
     files;
     constructor(ctx, env, app) {
         super(ctx, env);
@@ -44,17 +53,45 @@ export class PramenDOBase extends DurableObject {
         // The data layer runs over a Driver. The DO's store is its own in-process SQLite;
         // the D1 substrate (D1Driver) lives in the Worker (the "Worker + D1, no DO" path).
         this.driver = new DoSqliteDriver(ctx.storage);
-        // Reconcile the store with the schema before any request is served (create/alter
-        // tables; destructive changes rebuild the table). Wrapped in a transaction so a
-        // partial migration can't leave a half-rebuilt table.
-        const allowDestructive = env.PRAMEN_ALLOW_DESTRUCTIVE === "true";
-        ctx.blockConcurrencyWhile(() => this.driver.transaction(() => migrate(this.driver, this.app.schema, { allowDestructive }).then(() => { })));
+        // NOTE: the boot migration is NOT run here. The constructor cannot know which
+        // partition this DO serves — that arrives in the x-pramen-partition header on the
+        // first request, after construction. Migrating the full schema here would create
+        // OTHER partitions' tables in this DO (defeating partition isolation), so we defer
+        // the partition-scoped migrate() to the first fetch (`ensureMigrated`), guarded by
+        // ctx.blockConcurrencyWhile so concurrent first requests can't double-migrate.
+    }
+    // Reconcile this partition's tables with the schema before the first request is
+    // served. Runs once per DO lifetime: the `migrated` flag + blockConcurrencyWhile
+    // serialize concurrent first fetches (the platform queues other requests while the
+    // block runs), so two in-flight first requests can't both migrate. Scoped to
+    // this.partition — only this partition's tables are created/altered (migrate()
+    // never touches other partitions' tables). Wrapped in a transaction so a partial
+    // migration can't leave a half-rebuilt table. This preserves the single-partition
+    // (default) behavior exactly: a default DO migrates its full default-partition
+    // schema, just lazily on first touch instead of in the constructor.
+    async ensureMigrated() {
+        if (this.migrated)
+            return;
+        const allowDestructive = this.env.PRAMEN_ALLOW_DESTRUCTIVE === "true";
+        const partition = this.partition;
+        await this.ctx.blockConcurrencyWhile(async () => {
+            if (this.migrated)
+                return; // a concurrent first request already migrated
+            await this.driver.transaction(() => migrate(this.driver, this.app.schema, { allowDestructive, partition }).then(() => { }));
+            this.migrated = true;
+        });
     }
     async fetch(request) {
-        await this.ensureRegistered(request);
         const tenantHeader = request.headers.get("x-pramen-tenant");
         if (tenantHeader)
             this.tenant = tenantHeader;
+        // Learn the partition before the boot migration so it migrates the right subset.
+        // Absent header (shouldn't happen post-routing) -> default partition.
+        const partitionHeader = request.headers.get("x-pramen-partition");
+        if (partitionHeader)
+            this.partition = partitionHeader;
+        await this.ensureMigrated();
+        await this.ensureRegistered(request);
         const path = new URL(request.url).pathname;
         if (path === "/__recover")
             return this.handleRecover(request);
@@ -66,7 +103,7 @@ export class PramenDOBase extends DurableObject {
         if (request.headers.get("Upgrade") === "websocket") {
             const { 0: client, 1: server } = new WebSocketPair();
             this.ctx.acceptWebSocket(server); // hibernatable
-            this.setState(server, { identity, tenant: this.tenant, subs: [] });
+            this.setState(server, { identity, tenant: this.tenant, partition: this.partition, subs: [] });
             return new Response(null, { status: 101, webSocket: client });
         }
         const name = new URL(request.url).pathname.replace(/^\/rpc\//, "");
@@ -94,6 +131,15 @@ export class PramenDOBase extends DurableObject {
         catch {
             return this.send(ws, { type: "error", id: "", error: "invalid JSON" });
         }
+        // A hibernated DO can be reconstructed and routed here WITHOUT fetch() running
+        // again, so the boot migration may not have run on this fresh instance. Adopt this
+        // socket's (tenant, partition) — fixed at connect time, survives via the attachment
+        // — and ensure the schema is migrated before any handler/ctx.db work. Idempotent
+        // (the `migrated` flag), so a no-op after the first call.
+        const { tenant, partition } = this.getState(ws);
+        this.tenant = tenant;
+        this.partition = partition;
+        await this.ensureMigrated();
         switch (msg.type) {
             case "subscribe":
                 return this.onSubscribe(ws, msg.id, msg.name, msg.input);
@@ -128,7 +174,7 @@ export class PramenDOBase extends DurableObject {
             if (!replacing && state.subs.length >= MAX_SUBSCRIPTIONS) {
                 return this.send(ws, toWsError(id, new BadRequest("subscription limit reached")));
             }
-            const { result, kind, touched } = await dispatch(this.app.handlers, this.app.schema, this.driver, this.kv, this.filesFor(state.tenant), this.envBag, this.ctxFor(state.identity), name, input);
+            const { result, kind, touched } = await dispatch(this.app.handlers, this.app.schema, this.driver, this.kv, this.filesFor(state.tenant), this.envBag, this.ctxFor(state.identity, state.partition), name, input);
             if (kind !== "query") {
                 return this.send(ws, toWsError(id, new BadRequest(`${name} is not a query`)));
             }
@@ -144,7 +190,7 @@ export class PramenDOBase extends DurableObject {
     async onCall(ws, id, name, input) {
         const state = this.getState(ws);
         try {
-            const { result, kind, touched } = await dispatch(this.app.handlers, this.app.schema, this.driver, this.kv, this.filesFor(state.tenant), this.envBag, this.ctxFor(state.identity), name, input);
+            const { result, kind, touched } = await dispatch(this.app.handlers, this.app.schema, this.driver, this.kv, this.filesFor(state.tenant), this.envBag, this.ctxFor(state.identity, state.partition), name, input);
             this.send(ws, { type: "result", id, result });
             if (kind === "mutation" && touched.length > 0)
                 await this.broadcast(touched);
@@ -164,7 +210,7 @@ export class PramenDOBase extends DurableObject {
                 if (!sub.tables.some((t) => written.has(t)))
                     continue;
                 try {
-                    const { result } = await dispatch(this.app.handlers, this.app.schema, this.driver, this.kv, this.filesFor(state.tenant), this.envBag, this.ctxFor(state.identity), sub.name, sub.input);
+                    const { result } = await dispatch(this.app.handlers, this.app.schema, this.driver, this.kv, this.filesFor(state.tenant), this.envBag, this.ctxFor(state.identity, state.partition), sub.name, sub.input);
                     const next = digest(result);
                     if (next === sub.digest)
                         continue; // result unchanged for this subscription
@@ -196,7 +242,9 @@ export class PramenDOBase extends DurableObject {
             this.registered = true;
             return;
         }
-        await this.env.KV.put(`tenant:${name}`, JSON.stringify({ firstSeen: Date.now() }));
+        // Record under this DO's real (tenant, partition): the default partition keeps the
+        // bare `tenant:<name>` key (backward-compat), a non-default one is `tenant:<name>:<p>`.
+        await this.env.KV.put(registryKey(name, this.partition), JSON.stringify({ firstSeen: Date.now() }));
         await this.driver.exec(`INSERT OR REPLACE INTO _pramen_meta (key, value) VALUES ('registered', ?)`, [name]);
         this.registered = true;
     }
@@ -227,7 +275,11 @@ export class PramenDOBase extends DurableObject {
     // Introspection: this tenant's applied schema hash + live table/column shape
     // (admin-gated at the Worker). Powers the CLI's `schema status`.
     async handleSchema() {
-        const hashRow = (await this.driver.exec(`SELECT value FROM _pramen_meta WHERE key = 'schema_hash'`, []));
+        // The applied-schema hash is stored per-partition (migrate keys it
+        // `schema_hash:<partition>` whenever a partition is scoped, which the DO always
+        // does). Read this DO's partition's key.
+        const hashKey = `schema_hash:${this.partition}`;
+        const hashRow = (await this.driver.exec(`SELECT value FROM _pramen_meta WHERE key = ?`, [hashKey]));
         const tableRows = (await this.driver.exec(`SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name <> '_pramen_meta'`, []));
         const tables = {};
         for (const { name } of tableRows) {
@@ -246,7 +298,7 @@ export class PramenDOBase extends DurableObject {
             return Response.json({ ok: false, error: "unknown table", code: "bad_request" }, { status: 400 });
         }
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const db = new Db(this.driver, { acl: this.acl, identity: null, system: true }, this.app.schema);
+        const db = new Db(this.driver, { acl: this.acl, identity: null, system: true, partition: this.partition }, this.app.schema);
         try {
             let result;
             let mutated = false;
@@ -284,10 +336,11 @@ export class PramenDOBase extends DurableObject {
             return Response.json(body, { status });
         }
     }
-    ctxFor(identity) {
+    ctxFor(identity, partition = this.partition) {
         // Carry the schema so any consumer of this context (not just Db) can compile
-        // relation-aware `where` rules into subqueries.
-        return { acl: this.acl, identity, schema: this.app.schema };
+        // relation-aware `where` rules into subqueries, and the active partition so Db's
+        // table-access guard rejects any table outside this DO's partition.
+        return { acl: this.acl, identity, schema: this.app.schema, partition };
     }
     // The DO env (bindings + vars + secrets) handed to handlers as ctx.env. Loosely
     // typed at the boundary so handlers can read any var/secret without a DoEnv cast.
@@ -315,7 +368,12 @@ export class PramenDOBase extends DurableObject {
         }
     }
     getState(ws) {
-        return ws.deserializeAttachment() ?? { identity: null, tenant: this.tenant, subs: [] };
+        return (ws.deserializeAttachment() ?? {
+            identity: null,
+            tenant: this.tenant,
+            partition: this.partition,
+            subs: [],
+        });
     }
     setState(ws, state) {
         ws.serializeAttachment(state);

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { Entity, defineSchema, renamedFrom, notNull, unique, indexed, defaultTo } from "./sdk/schema";
+export { Entity, defineSchema, renamedFrom, notNull, unique, indexed, defaultTo, primaryKey, generated } from "./sdk/schema";
+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 } from "./sdk/handlers";

package/dist/index.js

@@ -7,7 +7,8 @@
 // which only exists in the Workers runtime; keeping it separate lets the CLI, tests,
 // and codegen load an app.ts for its schema without dragging in the DO runtime.
 // --- schema authoring ---
-export { Entity, defineSchema, renamedFrom, notNull, unique, indexed, defaultTo } from "./sdk/schema";
+export { Entity, defineSchema, renamedFrom, notNull, unique, indexed, defaultTo, primaryKey, generated } from "./sdk/schema";
+export { isValidUuid } from "./sdk/uuid";
 // --- app + handlers ---
 export { createApp } from "./sdk/app";
 export { query, mutation } from "./sdk/handlers";

package/dist/runtime/acl.d.ts

@@ -26,6 +26,10 @@ export interface AclContext {
     /** The app schema — lets `where` rules traverse relations (`{ rel: { col } }`),
      * compiled to a subquery with the related entity's read scope AND-merged in. */
     readonly schema?: SchemaDef;
+    /** The partition this DO serves. When set, Db rejects any access to a table that
+     * lives in a different partition (a partition-DO only owns its own tables). Unset
+     * (e.g. the D1/Worker shared-store path) disables the guard — a no-op. */
+    readonly partition?: string;
 }
 /** Evaluate every resolver reachable by the identity's roles, once per request.
  * Resolvers read through a SYSTEM-mode db (ACL bypassed) to avoid recursion. */

package/dist/runtime/db.d.ts

@@ -1,7 +1,7 @@
 import { type AclContext } from "./acl";
 import { type AggFn } from "./read-engine";
 import type { Driver } from "./driver";
-import type { EntityFields, SchemaDef } from "../sdk/schema";
+import { type EntityFields, type SchemaDef } from "../sdk/schema";
 import type { Cell, FieldsOf, InferInsert, InferRow, InferUpdate, RelationsOf, RelationsResult, WhereClause } from "../sdk/infer";
 type Row = Record<string, unknown>;
 type Id = string | number | bigint;
@@ -65,6 +65,13 @@ export declare class Db<S extends SchemaDef = SchemaDef> {
     private readonly dialect;
     private readonly acl;
     constructor(driver: Driver, acl: AclContext, schema: SchemaDef);
+    /** Partition guard. When this Db's context carries an active partition (a
+     * partition-DO knows which partition it serves), reject any access to a table
+     * that lives in a different partition — a partition-DO only owns its own tables,
+     * so touching another partition's table is a routing bug, not an empty result.
+     * Unset partition (the D1/Worker shared-store path, or a single-partition app on
+     * the default DO with no header) makes this a no-op. */
+    private assertInPartition;
     /** Resolve the ACL scope for an operation, or grant everything in SYSTEM mode. */
     private scopeFor;
     /** Forced `set` values + validators for a write (empty in SYSTEM mode). The two
@@ -113,6 +120,13 @@ export declare class Db<S extends SchemaDef = SchemaDef> {
     private assertReadableWhere;
     private selectRaw;
     private jsonColsOf;
+    /** Mint a UUID for every `generated()` uuid column the caller omitted, mutating
+     * `vals`. Returns the columns it filled — server-minted, so the insert path treats
+     * them like forced `set` values (bypassing the writable-field ACL check). */
+    private fillGeneratedUuids;
+    /** Reject a malformed value on any uuid column present in `row` (mirrors kvalt's
+     * write-time isValidUuid). Absent columns are not checked. */
+    private assertValidUuids;
     private decodeRows;
     private decodeRow;
     /** Encode one write cell: JSON-stringify a json/fileRef value, then dialect-encode. */

package/dist/runtime/db.js

@@ -13,6 +13,8 @@
 import { AclDenied, ALLOW_ALL, compileScopedWhere, effectiveFields, projectRow, resolveRelationScope, resolveScope, resolveWriteRules, } from "./acl";
 import { and, cmp, compileAggregate, compileCount, compileExpr, compileSelect, eq, inList, or, TRUE, } from "./read-engine";
 import { BadRequest } from "./errors";
+import { partitionOf } from "../sdk/schema";
+import { isValidUuid } from "../sdk/uuid";
 const DEFAULT_PAGE_SIZE = 50;
 function normalizeOrder(orderBy) {
     if (!orderBy)
@@ -64,6 +66,21 @@ export class Db {
         this.acl = acl.schema ? acl : { ...acl, schema };
         this.dialect = driver.dialect;
     }
+    /** Partition guard. When this Db's context carries an active partition (a
+     * partition-DO knows which partition it serves), reject any access to a table
+     * that lives in a different partition — a partition-DO only owns its own tables,
+     * so touching another partition's table is a routing bug, not an empty result.
+     * Unset partition (the D1/Worker shared-store path, or a single-partition app on
+     * the default DO with no header) makes this a no-op. */
+    assertInPartition(table) {
+        const self = this.acl.partition;
+        if (self === undefined)
+            return;
+        const tablePartition = partitionOf(this.schema, table);
+        if (tablePartition !== self) {
+            throw new BadRequest(`table '${table}' is in partition '${tablePartition}', not this partition '${self}'`);
+        }
+    }
     /** Resolve the ACL scope for an operation, or grant everything in SYSTEM mode. */
     scopeFor(entity, action) {
         if (this.acl.system)
@@ -116,6 +133,7 @@ export class Db {
     async find(spec) {
         const from = spec.from;
         this.touched.add(from);
+        this.assertInPartition(from);
         const scope = this.scopeFor(from, "read");
         if (!scope.allowed)
             throw new AclDenied(from, "read");
@@ -132,6 +150,7 @@ export class Db {
     async page(spec) {
         const from = spec.from;
         this.touched.add(from);
+        this.assertInPartition(from);
         const scope = this.scopeFor(from, "read");
         if (!scope.allowed)
             throw new AclDenied(from, "read");
@@ -154,6 +173,7 @@ export class Db {
     async count(spec) {
         const from = spec.from;
         this.touched.add(from);
+        this.assertInPartition(from);
         const scope = this.scopeFor(from, "read");
         if (!scope.allowed)
             throw new AclDenied(from, "read");
@@ -169,6 +189,7 @@ export class Db {
     async aggregate(spec) {
         const from = spec.from;
         this.touched.add(from);
+        this.assertInPartition(from);
         const scope = this.scopeFor(from, "read");
         if (!scope.allowed)
             throw new AclDenied(from, "read");
@@ -243,6 +264,37 @@ export class Db {
             .filter(([, f]) => f.type === "json" || f.type === "fileRef")
             .map(([n]) => n);
     }
+    /** Mint a UUID for every `generated()` uuid column the caller omitted, mutating
+     * `vals`. Returns the columns it filled — server-minted, so the insert path treats
+     * them like forced `set` values (bypassing the writable-field ACL check). */
+    fillGeneratedUuids(table, vals) {
+        const fields = this.schema[table]?.fields;
+        if (!fields)
+            return [];
+        const minted = [];
+        for (const [name, f] of Object.entries(fields)) {
+            const fd = f;
+            if (fd.type === "uuid" && fd.generated && vals[name] == null) {
+                vals[name] = crypto.randomUUID();
+                minted.push(name);
+            }
+        }
+        return minted;
+    }
+    /** Reject a malformed value on any uuid column present in `row` (mirrors kvalt's
+     * write-time isValidUuid). Absent columns are not checked. */
+    assertValidUuids(table, row) {
+        const fields = this.schema[table]?.fields;
+        if (!fields)
+            return;
+        for (const [name, f] of Object.entries(fields)) {
+            if (f.type !== "uuid")
+                continue;
+            const v = row[name];
+            if (v != null && !isValidUuid(v))
+                throw new BadRequest(`invalid UUID for '${name}'`);
+        }
+    }
     decodeRows(table, rows) {
         const cols = this.jsonColsOf(table);
         if (cols.length === 0)
@@ -350,14 +402,19 @@ export class Db {
     /** Insert a single row, returning the persisted row. */
     async insert(table, values) {
         this.touched.add(table);
+        this.assertInPartition(table);
         const scope = this.scopeFor(table, "create");
         if (!scope.allowed)
             throw new AclDenied(table, "create");
         const vals = { ...values };
         const { set, validators } = this.writeRules(table, "create");
         Object.assign(vals, set); // forced server values first, so a conditional `when` can see them
-        this.checkWriteFields(table, "create", scope, Object.keys(vals), vals, new Set(Object.keys(set)));
+        // Auto-mint generated() uuid columns the caller omitted; server-minted, so they
+        // join `set` in the bypass-list for the writable-field check.
+        const generatedCols = this.fillGeneratedUuids(table, vals);
+        this.checkWriteFields(table, "create", scope, Object.keys(vals), vals, new Set([...Object.keys(set), ...generatedCols]));
         this.runValidators(validators, vals);
+        this.assertValidUuids(table, vals);
         const cols = Object.keys(vals);
         const jsonCols = new Set(this.jsonColsOf(table));
         const colList = cols.map((c) => this.dialect.id(c)).join(", ");
@@ -390,6 +447,7 @@ export class Db {
      * only update rows within scope; returns undefined if none matched. */
     async update(table, id, patch) {
         this.touched.add(table);
+        this.assertInPartition(table);
         const scope = this.scopeFor(table, "update");
         if (!scope.allowed)
             throw new AclDenied(table, "update");
@@ -410,6 +468,7 @@ export class Db {
         }
         this.checkWriteFields(table, "update", scope, cols, evalRow, new Set(Object.keys(set)));
         this.runValidators(validators, p);
+        this.assertValidUuids(table, p);
         const params = [];
         const jsonCols = new Set(this.jsonColsOf(table));
         const assignments = cols
@@ -428,6 +487,7 @@ export class Db {
     /** Delete a row by id within scope. Returns whether a row was deleted. */
     async delete(table, id) {
         this.touched.add(table);
+        this.assertInPartition(table);
         const scope = this.scopeFor(table, "delete");
         if (!scope.allowed)
             throw new AclDenied(table, "delete");

package/dist/runtime/ddl.js

@@ -1,10 +1,14 @@
 // DDL generation — CREATE TABLE for a new entity and the additive ALTER fragment
 // for a new column. Runs in TS inside the isolate; see runtime/migrate.ts for how
 // these are applied.
-// SQLite has no boolean type; store as INTEGER 0/1. json + fileRef are stored as
-// TEXT (JSON). Exported for the migrator, which compares declared column types
+// SQLite has no boolean type; store as INTEGER 0/1. json + fileRef + uuid are
+// stored as TEXT. Exported for the migrator, which compares declared column types
 // (and CASTs on a type change).
-export const sqlType = (f) => f.type === "boolean" ? "INTEGER" : f.type === "json" || f.type === "fileRef" ? "TEXT" : f.type.toUpperCase();
+export const sqlType = (f) => f.type === "boolean"
+    ? "INTEGER"
+    : f.type === "json" || f.type === "fileRef" || f.type === "uuid"
+        ? "TEXT"
+        : f.type.toUpperCase();
 /** Render a DEFAULT literal. Strings are single-quote-escaped; booleans → 0/1. */
 function defaultLiteral(v) {
     if (v === null)

package/dist/runtime/dispatch.js

@@ -26,9 +26,9 @@ export async function dispatch(handlers, schema, driver, kv, files, env, acl, na
     }
     // Warmup: evaluate dynamic resolvers once, reading through a SYSTEM-mode db
     // (separate from the handler's db, so its reads don't pollute `touched`).
-    const systemDb = new Db(driver, { acl: acl.acl, identity: acl.identity, system: true, schema }, schema);
+    const systemDb = new Db(driver, { acl: acl.acl, identity: acl.identity, system: true, schema, partition: acl.partition }, schema);
     const resolved = await warmup(acl.acl, acl.identity, systemDb);
-    const db = new Db(driver, { acl: acl.acl, identity: acl.identity, input: parsed, resolved, schema }, schema);
+    const db = new Db(driver, { acl: acl.acl, identity: acl.identity, input: parsed, resolved, schema, partition: acl.partition }, schema);
     const ctx = { db, kv, files, env, identity: acl.identity };
     const result = handler.kind === "query"
         ? await handler.run(ctx, parsed)

package/dist/runtime/migrate.d.ts

@@ -17,6 +17,14 @@ export interface MigrateOptions {
      * — data-loss is gated behind an explicit opt-in (env `PRAMEN_ALLOW_DESTRUCTIVE`).
      * Additive changes (create table, add column, add index) always apply. */
     allowDestructive?: boolean;
+    /** Scope the migration to a single partition (Durable Object class). When set,
+     * migrate operates ONLY on entities whose `partition` matches — it creates/alters
+     * just that partition's tables and never drops other partitions' tables (a
+     * partition-DO never sees them). The schema hash is stored under a per-partition
+     * key so partitions don't thrash each other's drift detection. When unset, all
+     * entities are migrated and the legacy single-hash key is used (unchanged — the
+     * D1 path and existing callers). */
+    partition?: string;
 }
 export declare function schemaHash(schema: SchemaDef): string;
 export declare function migrate(driver: Driver, schema: SchemaDef, opts?: MigrateOptions): Promise<MigrationReport>;

package/dist/runtime/migrate.js

@@ -19,6 +19,7 @@
 // so it must be declared with `renamedFrom`; otherwise it is applied as drop+add.
 import { addColumnSql, createTableSql, indexStatements, sqlType } from "./ddl";
 import { digest } from "./digest";
+import { entitiesInPartition, validateSchema } from "../sdk/schema";
 /** Internal bookkeeping tables the migrator must never touch — pramen's own, SQLite's,
  * and the substrate's (D1 keeps `_cf_*` / `d1_*` tables in sqlite_master and forbids
  * dropping them). Matched case-insensitively. */
@@ -79,17 +80,33 @@ async function rebuildTable(driver, table, def, live) {
     await driver.exec(`ALTER TABLE ${ident(tmp)} RENAME TO ${ident(table)}`, []);
 }
 export async function migrate(driver, schema, opts = {}) {
+    // Static schema invariants (relation targets exist, no cross-partition relations) —
+    // checked before any DDL so a bad schema fails fast on boot / the D1 path, not mid-migration.
+    validateSchema(schema);
     await driver.exec(`CREATE TABLE IF NOT EXISTS _pramen_meta (key TEXT PRIMARY KEY, value TEXT)`, []);
     const allowDestructive = opts.allowDestructive ?? false;
-    const current = schemaHash(schema);
-    if ((await readMeta(driver, "schema_hash")) === current)
+    // When a partition is named, narrow the schema to just that partition's entities —
+    // every later pass (create/alter/rebuild/drop/index/hash) iterates this subset, so
+    // a partition-DO only ever touches its own tables. Unset ⇒ the whole schema, the
+    // legacy (default) behavior.
+    const tables = opts.partition === undefined ? Object.keys(schema) : entitiesInPartition(schema, opts.partition);
+    const entries = tables.map((table) => [table, schema[table]]);
+    const inScope = new Set(tables);
+    // The schema hash is computed over the in-scope subset only, and stored under a
+    // per-partition meta key, so two partitions of the same app each detect just their
+    // own drift and never invalidate the other. The unscoped path keeps the original
+    // `schema_hash` key for backward compatibility (existing stores + the D1 path).
+    const subset = Object.fromEntries(entries);
+    const hashKey = opts.partition === undefined ? "schema_hash" : `schema_hash:${opts.partition}`;
+    const current = schemaHash(subset);
+    if ((await readMeta(driver, hashKey)) === current)
         return { changed: false, created: [], added: [], rebuilt: [], droppedTables: [], skipped: [] };
     const created = [];
     const added = [];
     const rebuilt = [];
     const droppedTables = [];
     const skipped = [];
-    for (const [table, def] of Object.entries(schema)) {
+    for (const [table, def] of entries) {
         const existing = await tableColumns(driver, table);
         if (existing.size === 0) {
             await driver.exec(createTableSql(table, def), []);
@@ -128,14 +145,21 @@ export async function migrate(driver, schema, opts = {}) {
     // Ensure unique/index declarations (idempotent, via IF NOT EXISTS). Indexes can be
     // added to an existing table without a rebuild; a stale index from a removed
     // declaration is left in place (cleanup is future work).
-    for (const [table, def] of Object.entries(schema)) {
+    for (const [table, def] of entries) {
         for (const stmt of indexStatements(table, def))
             await driver.exec(stmt, []);
     }
     // Drop tables the schema no longer declares (internal bookkeeping tables skipped).
+    // When scoped to a partition, a live table that belongs to ANOTHER partition's
+    // entity must NOT be dropped — a partition-DO never owns it, and even when several
+    // partitions share a store the other partition's reconciler owns that table. So the
+    // drop candidate set is: live tables that are neither in this scope's declared
+    // entities nor declared by any other partition. (Unscoped: `otherPartitionTables`
+    // is empty and `inScope` is every entity, so this is the original behavior.)
+    const otherPartitionTables = opts.partition === undefined ? new Set() : new Set(Object.keys(schema).filter((t) => !inScope.has(t)));
     const liveTables = (await driver.exec(`SELECT name FROM sqlite_master WHERE type = 'table'`, []));
     for (const { name } of liveTables) {
-        if (isInternalTable(name) || name in schema)
+        if (isInternalTable(name) || inScope.has(name) || otherPartitionTables.has(name))
             continue;
         if (allowDestructive) {
             await driver.exec(`DROP TABLE ${ident(name)}`, []);
@@ -149,7 +173,7 @@ export async function migrate(driver, schema, opts = {}) {
     // were skipped, leave the hash so a later deploy (with allowDestructive) retries —
     // additive work is idempotent, so re-running is safe.
     if (skipped.length === 0) {
-        await writeMeta(driver, "schema_hash", current);
+        await writeMeta(driver, hashKey, current);
     }
     else {
         console.warn(`pramen: ${skipped.length} destructive migration(s) skipped (set PRAMEN_ALLOW_DESTRUCTIVE=true to apply): ${skipped.join("; ")}`);

package/dist/runtime/registry.d.ts

@@ -0,0 +1,28 @@
+/** A registered Durable Object identity: a (tenant, partition) pair. */
+export interface DoRef {
+    readonly tenant: string;
+    readonly partition: string;
+}
+/** Reject a tenant/partition name that would make a registry key ambiguous. A name
+ * may not be empty and may not contain `:` (the key separator). Throws on violation. */
+export declare function assertValidName(kind: "tenant" | "partition", name: string): void;
+/** Build the registry KV key for a `(tenant, partition)`. The default partition keeps
+ * the bare `tenant:<t>` key (backward-compat); any other partition is `tenant:<t>:<p>`.
+ * Rejects names containing `:` so the key parses unambiguously. */
+export declare function registryKey(tenant: string, partition?: string): string;
+/** Build the Durable Object NAME for a `(tenant, partition)` — the string passed to
+ * `idFromName`. This is the same default/non-default rule as `registryKey` but WITHOUT
+ * the KV `tenant:` prefix: the DO namespace and the KV registry are distinct keyspaces.
+ * Default partition keeps the BARE `tenant` name (byte-for-byte the pre-partition DO
+ * name — a hard backward-compat requirement: changing it would orphan existing DOs);
+ * any other partition is `${tenant}:${partition}`. Keeping it next to `registryKey`
+ * keeps routing and the registry derived from one place. */
+export declare function partitionDoName(tenant: string, partition?: string): string;
+/** Parse a registry KV key back into a `(tenant, partition)`. A bare `tenant:<t>`
+ * key yields partition `"default"`; `tenant:<t>:<p>` yields `<p>`. Returns null if
+ * the key is not a registry key (missing the `tenant:` prefix). */
+export declare function parseRegistryKey(key: string): DoRef | null;
+/** Enumerate every registered `(tenant, partition)` pair from the registry KV.
+ * Paginates over the full listing (cursor / list_complete) — never truncates at the
+ * 1000-key page limit. */
+export declare function listDOs(kv: KVNamespace): Promise<DoRef[]>;