@pramen/server 0.0.3 → 0.0.5

package/dist/runtime/registry.js

@@ -0,0 +1,88 @@
+// DO registry — the source of truth for which `(tenant, partition)` Durable Objects
+// exist. A `DurableObjectNamespace` has NO list/enumerate API (only idFromName /
+// idFromString / newUniqueId / get), so the platform cannot tell us which DOs were
+// ever instantiated. The only way to "work with all DOs" (migrate, recover, browse)
+// is this registry we maintain ourselves: each DO self-registers once (durable-object.ts
+// `ensureRegistered`), and admin ops enumerate via `listDOs`.
+//
+// This file owns the KV key scheme so the Worker and the DO agree on the format. It
+// is deliberately free of `cloudflare:workers` imports — it takes a `KVNamespace`
+// param, mirroring runtime/kv.ts.
+//
+// KEY SCHEME (hard backward-compat requirement):
+//   - default partition  → BARE  `tenant:<t>`        (NO `:default` suffix)
+//   - non-default        →       `tenant:<t>:<p>`
+// The bare-key-for-default rule keeps existing registry entries and DO routing keys
+// unchanged for single-partition apps. Adding a `:default` suffix would orphan all
+// existing data, so it must never appear in a key.
+//
+// NAME RULE: tenant and partition names MUST NOT contain `:`. The key format is
+// `tenant:<t>` / `tenant:<t>:<p>`, so a `:` in a name would make parsing ambiguous
+// (we couldn't tell where the tenant ends and the partition begins). Names are
+// validated at the boundary (here, when building a key) and rejected otherwise.
+import { DEFAULT_PARTITION } from "../sdk/schema";
+const KEY_PREFIX = "tenant:";
+/** 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 function assertValidName(kind, name) {
+    if (name.length === 0) {
+        throw new Error(`pramen: ${kind} name must not be empty`);
+    }
+    if (name.includes(":")) {
+        throw new Error(`pramen: ${kind} name "${name}" must not contain ':' (it is the registry key separator)`);
+    }
+}
+/** 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 function registryKey(tenant, partition = DEFAULT_PARTITION) {
+    assertValidName("tenant", tenant);
+    assertValidName("partition", partition);
+    return partition === DEFAULT_PARTITION ? `${KEY_PREFIX}${tenant}` : `${KEY_PREFIX}${tenant}:${partition}`;
+}
+/** 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 function partitionDoName(tenant, partition = DEFAULT_PARTITION) {
+    assertValidName("tenant", tenant);
+    assertValidName("partition", partition);
+    return partition === DEFAULT_PARTITION ? tenant : `${tenant}:${partition}`;
+}
+/** 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 function parseRegistryKey(key) {
+    if (!key.startsWith(KEY_PREFIX))
+        return null;
+    const rest = key.slice(KEY_PREFIX.length);
+    // At most one `:` remains (names exclude `:`), separating tenant from partition.
+    const sep = rest.indexOf(":");
+    if (sep === -1)
+        return { tenant: rest, partition: DEFAULT_PARTITION };
+    return { tenant: rest.slice(0, sep), partition: rest.slice(sep + 1) };
+}
+/** 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 async function listDOs(kv) {
+    const out = [];
+    let cursor;
+    for (;;) {
+        const res = await kv.list({ prefix: KEY_PREFIX, cursor });
+        for (const k of res.keys) {
+            const ref = parseRegistryKey(k.name);
+            if (ref)
+                out.push(ref);
+        }
+        if (res.list_complete)
+            break;
+        cursor = res.cursor;
+        if (!cursor)
+            break;
+    }
+    return out;
+}

package/dist/sdk/app.js

@@ -5,7 +5,7 @@
 //   const { query, mutation } = createApp(schema);
 //   const listNotes = query((ctx) => ctx.db.find({ from: "notes" })); // typed!
 export function createApp(schema) {
-    const query = (run, opts) => ({ kind: "query", run: run, input: opts?.input });
-    const mutation = (run, opts) => ({ kind: "mutation", run: run, input: opts?.input });
+    const query = (run, opts) => ({ kind: "query", run: run, input: opts?.input, partition: opts?.partition });
+    const mutation = (run, opts) => ({ kind: "mutation", run: run, input: opts?.input, partition: opts?.partition });
     return { schema, query, mutation };
 }

package/dist/sdk/handlers.d.ts

@@ -27,9 +27,15 @@ export interface Handler<I = unknown, O = unknown> {
     /** Optional boundary validator: parse/validate the raw request input, throwing
      * to reject (surfaced as a 400). Its return type fixes the handler's input. */
     readonly input?: (raw: unknown) => unknown;
+    /** Optional DO partition this handler runs in (static, server-side). The Worker
+     * routes the request to the matching partition-DO before dispatch. Absent ⇒ the
+     * default partition (routed to the bare tenant key). */
+    readonly partition?: string;
 }
 export interface HandlerOpts<I> {
     input?: (raw: unknown) => I;
+    /** DO partition this handler runs in. Absent ⇒ the default partition. */
+    partition?: string;
 }
 export declare function query<I = unknown, O = unknown>(run: (ctx: HandlerContext, input: I) => O | Promise<O>, opts?: HandlerOpts<I>): Handler<I, O>;
 export declare function mutation<I = unknown, O = unknown>(run: (ctx: HandlerContext, input: I) => O | Promise<O>, opts?: HandlerOpts<I>): Handler<I, O>;

package/dist/sdk/handlers.js

@@ -4,8 +4,8 @@
 // Standalone (schema-agnostic) handler factories. Prefer createApp(schema) for a
 // typed ctx.db; these remain for untyped/ad-hoc use.
 export function query(run, opts) {
-    return { kind: "query", run, input: opts?.input };
+    return { kind: "query", run, input: opts?.input, partition: opts?.partition };
 }
 export function mutation(run, opts) {
-    return { kind: "mutation", run, input: opts?.input };
+    return { kind: "mutation", run, input: opts?.input, partition: opts?.partition };
 }

package/dist/sdk/infer.d.ts

@@ -6,7 +6,7 @@ export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
 /** SQL field type -> TypeScript value type. */
-export type FieldTsType<D extends FieldDef> = D["type"] extends "text" ? string : D["type"] extends "boolean" ? boolean : D["type"] extends "json" ? JsonValue : D["type"] extends "fileRef" ? FileRef : number;
+export type FieldTsType<D extends FieldDef> = D["type"] extends "text" ? string : D["type"] extends "boolean" ? boolean : D["type"] extends "json" ? JsonValue : D["type"] extends "fileRef" ? FileRef : D["type"] extends "uuid" ? string : number;
 /** A column is non-null iff it's NOT NULL or a primary key. */
 type IsNotNull<D extends FieldDef> = D extends {
     notNull: true;
@@ -61,8 +61,12 @@ export type InferUpdate<F extends EntityFields> = Partial<{
 type RequiredInsertKeys<F extends EntityFields> = {
     [K in keyof F]: IsNotNull<F[K]> extends true ? F[K] extends {
         autoIncrement: true;
+    } ? never : F[K] extends {
+        generated: true;
     } ? never : F[K] extends {
         default: DefaultValue;
+    } ? never : F[K] extends {
+        defaultExpr: string;
     } ? never : K : never;
 }[keyof F];
 type OptionalInsertKeys<F extends EntityFields> = Exclude<keyof F, RequiredInsertKeys<F>>;

package/dist/sdk/schema.d.ts

@@ -1,4 +1,4 @@
-export type FieldType = "text" | "integer" | "real" | "boolean" | "json" | "fileRef";
+export type FieldType = "text" | "integer" | "real" | "boolean" | "json" | "fileRef" | "uuid";
 /** A SQL DEFAULT literal (used by the migrator + DDL). */
 export type DefaultValue = string | number | boolean | null;
 export interface FieldDef {
@@ -10,8 +10,16 @@ export interface FieldDef {
     readonly unique?: boolean;
     /** A (non-unique) index on this column. */
     readonly index?: boolean;
+    /** Auto-generate the value on insert when the caller omits it (uuid columns only,
+     * minted via crypto.randomUUID()). Set by the `generated()` modifier; makes the
+     * column optional on insert. */
+    readonly generated?: boolean;
     /** A column DEFAULT (a literal). Makes the column optional on insert. */
     readonly default?: DefaultValue;
+    /** A column DEFAULT that is raw SQL, emitted UNQUOTED (e.g. `datetime('now')`) —
+     * set by `defaultTo(field, expr.now())`/`expr.raw(...)`. Distinct from `default`
+     * (a quoted literal). Makes the column optional on insert. */
+    readonly defaultExpr?: string;
     /** Migration hint: this column was previously named X. On boot the migrator
      * rebuilds the table, copying data from the old column. A diff cannot tell a
      * rename from a drop+add, so the rename must be declared explicitly. */
@@ -51,6 +59,12 @@ declare const builders: {
     fileRef: () => {
         readonly type: "fileRef";
     };
+    /** A UUID stored in a TEXT column (typed as `string`). Wrap with `generated()` to
+     * auto-mint a v4 on insert, and/or `primaryKey()` to use it as the PK — the kvalt
+     * pattern `id: primaryKey(generated(t.uuid()))`. A provided value is validated. */
+    uuid: () => {
+        readonly type: "uuid";
+    };
 };
 export type FieldBuilders = typeof builders;
 export type EntityFields = Record<string, FieldDef>;
@@ -81,11 +95,18 @@ declare const relationBuilders: {
     };
 };
 export type RelationBuilders = typeof relationBuilders;
+/** The default partition name for entities that don't declare one. */
+export declare const DEFAULT_PARTITION = "default";
 export interface EntityDef<F extends EntityFields = EntityFields, R extends RelationDefs = Record<string, never>> {
     readonly fields: F;
     readonly relations: R;
+    /** The partition (Durable Object class) this entity lives in. Always populated;
+     * defaults to `"default"` so downstream code never branches on `undefined`. */
+    readonly partition: string;
 }
-export declare function Entity<F extends EntityFields, R extends RelationDefs = Record<string, never>>(build: (t: FieldBuilders) => F, relations?: (r: RelationBuilders) => R): EntityDef<F, R>;
+export declare function Entity<F extends EntityFields, R extends RelationDefs = Record<string, never>>(build: (t: FieldBuilders) => F, relations?: (r: RelationBuilders) => R, opts?: {
+    partition?: string;
+}): EntityDef<F, R>;
 /** Annotate a field as renamed from a previous column name (migration hint). Wraps
  * a builder result, preserving its literal field type: `title: renamedFrom(t.text(), "name")`. */
 export declare function renamedFrom<F extends FieldDef>(field: F, from: string): F & {
@@ -103,10 +124,59 @@ export declare function unique<F extends FieldDef>(field: F): F & {
 export declare function indexed<F extends FieldDef>(field: F): F & {
     readonly index: true;
 };
-/** Give the column a DEFAULT (a literal) — also makes it optional on insert. */
+/** A raw-SQL column DEFAULT (emitted unquoted in the DDL), produced by the `expr`
+ * helpers below. Distinct from a literal default so `defaultTo` can render
+ * `DEFAULT datetime('now')` rather than the quoted string `DEFAULT 'datetime(...)'`. */
+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. */
+export declare const expr: {
+    now: () => ExprDefault;
+    raw: (sql: string) => ExprDefault;
+};
+/** Give the column a DEFAULT — also makes it optional on insert. Pass a literal
+ * (rendered as a quoted SQL literal) or an `expr.*()` value (raw SQL, unquoted),
+ * e.g. `defaultTo(t.text(), "pending")` or `defaultTo(t.text(), expr.now())`. */
+export declare function defaultTo<F extends FieldDef>(field: F, value: ExprDefault): F & {
+    readonly defaultExpr: string;
+};
 export declare function defaultTo<F extends FieldDef, D extends DefaultValue>(field: F, value: D): F & {
     readonly default: D;
 };
+/** Mark a column as the PRIMARY KEY (implies NOT NULL). Composes with any builder,
+ * e.g. `id: primaryKey(generated(t.uuid()))` or `code: primaryKey(t.text())`. */
+export declare function primaryKey<F extends FieldDef>(field: F): F & {
+    readonly primaryKey: true;
+    readonly notNull: true;
+};
+/** Auto-generate the column's value on insert when omitted — uuid only (minted via
+ * crypto.randomUUID()). Makes the column optional on insert. Rejected at schema
+ * construction on a non-uuid column, since the runtime only knows how to mint uuids. */
+export declare function generated<F extends FieldDef>(field: F): F & {
+    readonly generated: true;
+};
 export type SchemaDef = Record<string, EntityDef<EntityFields, RelationDefs>>;
 export declare function defineSchema<S extends SchemaDef>(entities: S): S;
+/** The partition an entity lives in. Defaults to `"default"` for unknown entities. */
+export declare function partitionOf(schema: SchemaDef, entity: string): string;
+/** The distinct partition names in a schema, in stable (first-seen) order. */
+export declare function partitionsOf(schema: SchemaDef): string[];
+/** The table names whose partition matches `partition`, in schema (key) order. */
+export declare function entitiesInPartition(schema: SchemaDef, partition: string): string[];
+/**
+ * Validate a schema's static invariants, throwing on the first violation:
+ *
+ *  - every relation's `target` names an entity that exists in the schema;
+ *  - no relation crosses a partition boundary — a relation's source and target
+ *    must live in the same partition (a Durable Object can't reach into another).
+ *
+ * Relations are static, so these are caught at validation time (boot + codegen),
+ * never as a runtime surprise. Runs even for a single (default) partition — it's
+ * cheap and catches relation-target typos.
+ */
+export declare function validateSchema(schema: SchemaDef): void;
 export {};

package/dist/sdk/schema.js

@@ -19,13 +19,23 @@ const builders = {
     /** A reference to a stored file (R2 object). Holds JSON metadata (a FileRef),
      * not the bytes — upload/download go through ctx.files + the Worker /files/* route. */
     fileRef: () => ({ type: "fileRef" }),
+    /** A UUID stored in a TEXT column (typed as `string`). Wrap with `generated()` to
+     * auto-mint a v4 on insert, and/or `primaryKey()` to use it as the PK — the kvalt
+     * pattern `id: primaryKey(generated(t.uuid()))`. A provided value is validated. */
+    uuid: () => ({ type: "uuid" }),
 };
 const relationBuilders = {
     belongsTo: (target, column) => ({ kind: "belongsTo", target, column }),
     hasMany: (target, column) => ({ kind: "hasMany", target, column }),
 };
-export function Entity(build, relations) {
-    return { fields: build(builders), relations: (relations ? relations(relationBuilders) : {}) };
+/** The default partition name for entities that don't declare one. */
+export const DEFAULT_PARTITION = "default";
+export function Entity(build, relations, opts) {
+    return {
+        fields: build(builders),
+        relations: (relations ? relations(relationBuilders) : {}),
+        partition: opts?.partition ?? DEFAULT_PARTITION,
+    };
 }
 /** Annotate a field as renamed from a previous column name (migration hint). Wraps
  * a builder result, preserving its literal field type: `title: renamedFrom(t.text(), "name")`. */
@@ -47,10 +57,92 @@ export function unique(field) {
 export function indexed(field) {
     return { ...field, index: true };
 }
-/** Give the column a DEFAULT (a literal) — also makes it optional on insert. */
+/** A raw-SQL column DEFAULT (emitted unquoted in the DDL), produced by the `expr`
+ * helpers below. Distinct from a literal default so `defaultTo` can render
+ * `DEFAULT datetime('now')` rather than the quoted string `DEFAULT 'datetime(...)'`. */
+export class ExprDefault {
+    sql;
+    constructor(sql) {
+        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. */
+export const expr = {
+    now: () => new ExprDefault("datetime('now')"),
+    raw: (sql) => new ExprDefault(sql),
+};
 export function defaultTo(field, value) {
-    return { ...field, default: value };
+    return value instanceof ExprDefault ? { ...field, defaultExpr: value.sql } : { ...field, default: value };
+}
+/** Mark a column as the PRIMARY KEY (implies NOT NULL). Composes with any builder,
+ * e.g. `id: primaryKey(generated(t.uuid()))` or `code: primaryKey(t.text())`. */
+export function primaryKey(field) {
+    return { ...field, primaryKey: true, notNull: true };
+}
+/** Auto-generate the column's value on insert when omitted — uuid only (minted via
+ * crypto.randomUUID()). Makes the column optional on insert. Rejected at schema
+ * construction on a non-uuid column, since the runtime only knows how to mint uuids. */
+export function generated(field) {
+    if (field.type !== "uuid") {
+        throw new Error(`generated() is only valid on a uuid column (got '${field.type}')`);
+    }
+    return { ...field, generated: true };
 }
 export function defineSchema(entities) {
     return entities;
 }
+// --- partition helpers — enumerate / resolve the partition (Durable Object class)
+// an entity lives in. Used by the migrator/admin to group tables per DO.
+/** The partition an entity lives in. Defaults to `"default"` for unknown entities. */
+export function partitionOf(schema, entity) {
+    return schema[entity]?.partition ?? DEFAULT_PARTITION;
+}
+/** The distinct partition names in a schema, in stable (first-seen) order. */
+export function partitionsOf(schema) {
+    const seen = new Set();
+    const out = [];
+    for (const entity of Object.keys(schema)) {
+        const partition = partitionOf(schema, entity);
+        if (!seen.has(partition)) {
+            seen.add(partition);
+            out.push(partition);
+        }
+    }
+    return out;
+}
+/** The table names whose partition matches `partition`, in schema (key) order. */
+export function entitiesInPartition(schema, partition) {
+    return Object.keys(schema).filter((entity) => partitionOf(schema, entity) === partition);
+}
+// --- schema validation — static invariants checked once before migrate (DO boot
+// + the D1 path) and at codegen. Cloudflare-free, so it stays in sdk/.
+/**
+ * Validate a schema's static invariants, throwing on the first violation:
+ *
+ *  - every relation's `target` names an entity that exists in the schema;
+ *  - no relation crosses a partition boundary — a relation's source and target
+ *    must live in the same partition (a Durable Object can't reach into another).
+ *
+ * Relations are static, so these are caught at validation time (boot + codegen),
+ * never as a runtime surprise. Runs even for a single (default) partition — it's
+ * cheap and catches relation-target typos.
+ */
+export function validateSchema(schema) {
+    for (const [entity, def] of Object.entries(schema)) {
+        for (const [relName, rel] of Object.entries(def.relations)) {
+            if (!(rel.target in schema)) {
+                throw new Error(`relation '${entity}.${relName}' targets unknown entity '${rel.target}' — ` +
+                    `no such entity in the schema. Check the relation target name.`);
+            }
+            const pE = partitionOf(schema, entity);
+            const pT = partitionOf(schema, rel.target);
+            if (pE !== pT) {
+                throw new Error(`relation '${entity}.${relName}' crosses a partition boundary: '${entity}' is in partition ` +
+                    `'${pE}' but target '${rel.target}' is in '${pT}'. Relations cannot cross partitions — ` +
+                    `put both entities in the same partition or drop the relation.`);
+            }
+        }
+    }
+}

package/dist/sdk/uuid.d.ts

@@ -0,0 +1,2 @@
+/** Whether `v` is a syntactically valid UUID string. */
+export declare function isValidUuid(v: unknown): v is string;

package/dist/sdk/uuid.js

@@ -0,0 +1,10 @@
+// UUID format validation for `t.uuid()` columns. Platform-agnostic (sdk layer):
+// the runtime validates a provided uuid value on write, and mints new ones via the
+// global crypto.randomUUID() (Workers/Bun/Node) — see runtime/db.ts.
+// Canonical 8-4-4-4-12 hex form, case-insensitive. Version/variant-agnostic so it
+// accepts v4 (what we generate) as well as v7 and others a caller might supply.
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Whether `v` is a syntactically valid UUID string. */
+export function isValidUuid(v) {
+    return typeof v === "string" && UUID_RE.test(v);
+}

package/dist/worker.d.ts

@@ -33,6 +33,7 @@ export declare function callPrivileged(env: Env, opts: {
     input?: unknown;
     tenant?: string;
     roles?: string[];
+    partition?: string;
 }): Promise<Response>;
 /** Build the Worker fetch handler for an app. State (the JWKS cache, the D1
  * compiled-ACL + one-time migration) is per-app, held in this closure. */

package/dist/worker.js

@@ -10,7 +10,9 @@ import { compileAcl } from "./runtime/acl";
 import { D1Driver } from "./runtime/driver";
 import { toResponse } from "./runtime/errors";
 import { Kv } from "./runtime/kv";
+import { listDOs, partitionDoName } from "./runtime/registry";
 import { createFiles, handleFileRequest, R2Adapter } from "./runtime/storage";
+import { DEFAULT_PARTITION } from "./sdk/schema";
 /** The secret used to sign/verify file tokens — a dedicated FILES_SECRET if set,
  * else AUTH_SECRET (so HS256 setups work out of the box). */
 const filesSecret = (env) => env.FILES_SECRET || env.AUTH_SECRET;
@@ -42,18 +44,27 @@ function withCors(res, cors) {
         headers.set(k, v);
     return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
 }
+/** Resolve the Durable Object stub for a `(tenant, partition)`. The DO name comes from
+ * `partitionDoName`, so routing and the registry stay in lockstep: it returns the BARE
+ * `tenant` for the default partition (so `idFromName(tenant)` is byte-for-byte unchanged
+ * — backward-compat) and `${tenant}:${partition}` for any other partition. */
+function partitionStubFor(env, tenant, partition = DEFAULT_PARTITION) {
+    return env.PRAMEN.get(env.PRAMEN.idFromName(partitionDoName(tenant, partition)));
+}
 /** Forward a privileged mutation into a tenant's DO from a public route. The
  * synthetic identity (default `["admin"]`) is trusted because the call originates
  * in the Worker — the same internal mechanism the admin endpoints use. Returns the
  * DO's JSON response (`{ ok, result }` / `{ ok: false, … }`). */
 export async function callPrivileged(env, opts) {
     const tenant = opts.tenant ?? "main";
-    const stub = env.PRAMEN.get(env.PRAMEN.idFromName(tenant));
+    const partition = opts.partition ?? DEFAULT_PARTITION;
+    const stub = partitionStubFor(env, tenant, partition);
     return stub.fetch(new Request(`https://do/rpc/${opts.name}`, {
         method: "POST",
         headers: {
             "content-type": "application/json",
             "x-pramen-tenant": tenant,
+            "x-pramen-partition": partition,
             "x-pramen-identity": JSON.stringify({ roles: opts.roles ?? ["admin"] }),
         },
         body: JSON.stringify(opts.input ?? {}),
@@ -125,15 +136,20 @@ export function makeWorker(app) {
                 const qTenant = url.searchParams.get("tenant");
                 if (qTenant && !h.get("x-pramen-tenant"))
                     h.set("x-pramen-tenant", qTenant);
+                // A single socket lives in one partition (cross-partition live is out of scope);
+                // accept it via ?partition= and default to the default partition.
+                const qPartition = url.searchParams.get("partition");
+                if (!h.get("x-pramen-partition"))
+                    h.set("x-pramen-partition", qPartition || DEFAULT_PARTITION);
                 req = new Request(request, { headers: h });
             }
             const identity = await resolveIdentity(req, strategyFor(env));
-            // --- admin: list known tenants ---
+            // --- admin: list known (tenant, partition) DOs from the registry ---
             if (url.pathname === "/tenants") {
                 if (!isAdmin(identity))
                     return withCors(forbidden("tenants"), cors);
-                const list = await env.KV.list({ prefix: "tenant:" });
-                return withCors(json({ ok: true, result: list.keys.map((k) => k.name.slice("tenant:".length)) }), cors);
+                const result = await listDOs(env.KV);
+                return withCors(json({ ok: true, result }), cors);
             }
             // --- admin: point-in-time recovery for a tenant ---
             if (url.pathname === "/admin/recover" && request.method === "POST") {
@@ -144,10 +160,11 @@ export function makeWorker(app) {
                     return badRequest("tenant required");
                 if (typeof body.timestamp !== "number" && typeof body.timestamp !== "string")
                     return badRequest("timestamp required");
-                const stub = env.PRAMEN.get(env.PRAMEN.idFromName(body.tenant));
+                const partition = typeof body.partition === "string" && body.partition ? body.partition : DEFAULT_PARTITION;
+                const stub = partitionStubFor(env, body.tenant, partition);
                 const internal = new Request("https://do/__recover", {
                     method: "POST",
-                    headers: { "content-type": "application/json", "x-pramen-tenant": body.tenant },
+                    headers: { "content-type": "application/json", "x-pramen-tenant": body.tenant, "x-pramen-partition": partition },
                     body: JSON.stringify({ timestamp: body.timestamp }),
                 });
                 return stub.fetch(internal);
@@ -157,8 +174,9 @@ export function makeWorker(app) {
                 if (!isAdmin(identity))
                     return withCors(forbidden("schema"), cors);
                 const tenant = url.searchParams.get("tenant") ?? "main";
-                const stub = env.PRAMEN.get(env.PRAMEN.idFromName(tenant));
-                const res = await stub.fetch(new Request("https://do/__schema", { headers: { "x-pramen-tenant": tenant } }));
+                const partition = url.searchParams.get("partition") || DEFAULT_PARTITION;
+                const stub = partitionStubFor(env, tenant, partition);
+                const res = await stub.fetch(new Request("https://do/__schema", { headers: { "x-pramen-tenant": tenant, "x-pramen-partition": partition } }));
                 return withCors(res, cors);
             }
             // --- admin: generic data ops over a tenant's tables (browse/edit any row).
@@ -169,10 +187,11 @@ export function makeWorker(app) {
                     return forbidden("data");
                 const body = (await request.json().catch(() => ({})));
                 const tenant = typeof body.tenant === "string" && body.tenant ? body.tenant : "main";
-                const stub = env.PRAMEN.get(env.PRAMEN.idFromName(tenant));
+                const partition = typeof body.partition === "string" && body.partition ? body.partition : DEFAULT_PARTITION;
+                const stub = partitionStubFor(env, tenant, partition);
                 const res = await stub.fetch(new Request("https://do/__admin/data", {
                     method: "POST",
-                    headers: { "content-type": "application/json", "x-pramen-tenant": tenant },
+                    headers: { "content-type": "application/json", "x-pramen-tenant": tenant, "x-pramen-partition": partition },
                     body: JSON.stringify(body),
                 }));
                 return withCors(res, cors);
@@ -182,8 +201,9 @@ export function makeWorker(app) {
             if (!isRpc && !(isLive && isWs)) {
                 return new Response("pramen — POST /rpc/<handler> (JSON body), or WebSocket /live for live queries. " +
                     "Header X-Pramen-Tenant selects the store (default: main). " +
-                    "Admin: GET /tenants, POST /admin/recover {tenant,timestamp}, GET /admin/schema?tenant=, " +
-                    "POST /admin/data {tenant,table,op}.\n", { headers: { "content-type": "text/plain" } });
+                    "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" } });
             }
             // Authorize the tenant against the identity before reaching the DO, so a
             // caller can't address (or register) tenants they have no claim to.
@@ -216,13 +236,25 @@ export function makeWorker(app) {
                     return withCors(json(body, status), cors);
                 }
             }
+            // Resolve the partition to route to. For /rpc it's declared statically on the
+            // handler; for /live it's the socket's partition (already folded into the header
+            // from ?partition=). Forward it to the DO in x-pramen-partition either way.
+            let partition;
+            if (isRpc) {
+                const name = url.pathname.replace(/^\/rpc\//, "");
+                partition = app.handlers[name]?.partition ?? DEFAULT_PARTITION;
+            }
+            else {
+                partition = req.headers.get("x-pramen-partition") || DEFAULT_PARTITION;
+            }
             // Forward a trusted identity to the DO (the DO never re-derives it).
             const headers = new Headers(req.headers);
             if (identity)
                 headers.set("x-pramen-identity", JSON.stringify(identity));
             else
                 headers.delete("x-pramen-identity");
-            const stub = env.PRAMEN.get(env.PRAMEN.idFromName(tenant));
+            headers.set("x-pramen-partition", partition);
+            const stub = partitionStubFor(env, tenant, partition);
             // WebSocket upgrades (101) must be returned untouched; only add CORS to HTTP.
             const res = await stub.fetch(new Request(req, { headers }));
             return isWs ? res : withCors(res, cors);

package/package.json

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