@pramen/server 0.0.2 → 0.0.4

package/src/sdk/infer.ts

@@ -20,7 +20,9 @@ export type FieldTsType<D extends FieldDef> = D["type"] extends "text"
       ? JsonValue
       : D["type"] extends "fileRef"
         ? FileRef
-        : number; // integer | real
+        : D["type"] extends "uuid"
+          ? string
+          : number; // integer | real
 
 /** A column is non-null iff it's NOT NULL or a primary key. */
 type IsNotNull<D extends FieldDef> = D extends { notNull: true }
@@ -62,6 +64,27 @@ export type WhereInput<F extends EntityFields> = {
   OR?: WhereInput<F>[];
 };
 
+// --- partition boundary: runtime-only by decision (Issue 08) ---
+//
+// A relation cannot cross a partition (Durable Object) boundary. That invariant is
+// enforced at runtime/boot by `validateSchema` (sdk/schema.ts) — it throws before
+// migrate if any relation's source and target live in different partitions — and is
+// proven end-to-end by the e2e suite (Issue 09).
+//
+// Issue 08 explored ALSO surfacing the boundary at compile time (dropping cross-
+// partition relation keys out of `WhereClause`'s relation half and `RelationsResult`,
+// so a cross-partition `with`/relation-`where` wouldn't even typecheck). That requires
+// the entity's `partition` to survive inference as a string LITERAL ("audit" vs
+// "default") so a conditional type can compare two literals. It does NOT: `EntityDef`
+// declares `readonly partition: string` and the `Entity()` factory returns
+// `EntityDef<F, R>` with `opts.partition?: string` — the literal is widened to `string`
+// at the factory boundary and is unrecoverable here. Carrying it would mean threading a
+// `P extends string` generic through `EntityDef` / `Entity` / `SchemaDef` and every
+// consumer (FieldsOf, RelationsOf, RelValue, …) in sdk/schema.ts, destabilizing the
+// already depth-bounded `WhereClause`/`RelationsResult`. Per the issue's explicit
+// bail-out, that is disproportionate for optional polish over an already-enforced
+// invariant. Decision: the partition boundary is enforced at runtime/boot only.
+//
 // --- relation-aware where (a relation key takes a nested clause over its target,
 // compiled to a security-scoped subquery). Depth-bounded so the type stays finite
 // under cyclic relations (e.g. user.notes ↔ note.owner). The bound matches the
@@ -76,21 +99,31 @@ export type WhereClause<S extends SchemaDef, T extends keyof S, D extends number
   ([D] extends [never]
     ? object
     : {
-        [K in keyof RelationsOf<S[T]>]?: WhereClause<S, RelTargetTable<S, RelationsOf<S[T]>[K]>, PrevDepth[D]>;
+        // Remap away the `string`/`number` index keys so a relationless entity
+        // (RelationsOf = Record<string, never>) contributes `{}`, not an index
+        // signature that would reject every column key in the WhereInput half.
+        [K in keyof RelationsOf<S[T]> as string extends K ? never : number extends K ? never : K]?: WhereClause<
+          S,
+          RelTargetTable<S, RelationsOf<S[T]>[K]>,
+          PrevDepth[D]
+        >;
       });
 
 /** Patch input for updates: every column optional, value typed (nullable). */
 export type InferUpdate<F extends EntityFields> = Partial<{ [K in keyof F]: FieldTsType<F[K]> | null }>;
 
-// Insert: a NOT NULL column is required unless it's auto-generated (autoIncrement)
-// or has a DEFAULT (the DB fills it); everything else is optional.
+// Insert: a NOT NULL column is required unless it's auto-generated (autoIncrement,
+// or a `generated()` uuid the runtime mints) or has a DEFAULT (the DB fills it);
+// everything else is optional.
 type RequiredInsertKeys<F extends EntityFields> = {
   [K in keyof F]: IsNotNull<F[K]> extends true
     ? F[K] extends { autoIncrement: true }
       ? never
-      : F[K] extends { default: DefaultValue }
+      : F[K] extends { generated: true }
         ? never
-        : K
+        : F[K] extends { default: DefaultValue }
+          ? never
+          : K
     : never;
 }[keyof F];
 type OptionalInsertKeys<F extends EntityFields> = Exclude<keyof F, RequiredInsertKeys<F>>;

package/src/sdk/schema.ts

@@ -9,8 +9,9 @@
 
 // "json" and "fileRef" are logical types stored as TEXT (JSON). The value a handler
 // reads/writes is the parsed value (a JsonValue, or a FileRef) — db.ts codecs it
-// to/from the column, and infer.ts types it accordingly.
-export type FieldType = "text" | "integer" | "real" | "boolean" | "json" | "fileRef";
+// to/from the column, and infer.ts types it accordingly. "uuid" is a TEXT column
+// typed as `string`; wrap it with `generated()` to auto-mint a v4 on insert.
+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;
@@ -24,6 +25,10 @@ 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;
   /** Migration hint: this column was previously named X. On boot the migrator
@@ -45,6 +50,10 @@ 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" }) as const,
+  /** 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" }) as const,
 };
 
 export type FieldBuilders = typeof builders;
@@ -73,16 +82,27 @@ const relationBuilders = {
 };
 export type RelationBuilders = typeof relationBuilders;
 
+/** The default partition name for entities that don't declare one. */
+export 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 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> {
-  return { fields: build(builders), relations: (relations ? relations(relationBuilders) : {}) as R };
+  return {
+    fields: build(builders),
+    relations: (relations ? relations(relationBuilders) : {}) as R,
+    partition: opts?.partition ?? DEFAULT_PARTITION,
+  };
 }
 
 /** Annotate a field as renamed from a previous column name (migration hint). Wraps
@@ -115,8 +135,87 @@ export function defaultTo<F extends FieldDef, D extends DefaultValue>(field: F,
   return { ...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<F extends FieldDef>(field: F): F & { readonly primaryKey: true; readonly notNull: true } {
+  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<F extends FieldDef>(field: F): F & { readonly generated: true } {
+  if (field.type !== "uuid") {
+    throw new Error(`generated() is only valid on a uuid column (got '${field.type}')`);
+  }
+  return { ...field, generated: true };
+}
+
 export type SchemaDef = Record<string, EntityDef<EntityFields, RelationDefs>>;
 
 export function defineSchema<S extends SchemaDef>(entities: S): S {
   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: SchemaDef, entity: string): string {
+  return schema[entity]?.partition ?? DEFAULT_PARTITION;
+}
+
+/** The distinct partition names in a schema, in stable (first-seen) order. */
+export function partitionsOf(schema: SchemaDef): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  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: SchemaDef, partition: string): string[] {
+  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: SchemaDef): void {
+  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/src/sdk/uuid.ts

@@ -0,0 +1,12 @@
+// 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: unknown): v is string {
+  return typeof v === "string" && UUID_RE.test(v);
+}

package/src/worker.ts

@@ -11,8 +11,10 @@ import { compileAcl } from "./runtime/acl";
 import { D1Driver, type Driver } 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 type { Identity } from "./sdk/acl";
+import { DEFAULT_PARTITION } from "./sdk/schema";
 import type { PramenApp } from "./pramen";
 
 export interface Env {
@@ -72,22 +74,32 @@ function withCors(res: Response, cors: Record<string, string>): Response {
   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: Env, tenant: string, partition: string = DEFAULT_PARTITION): DurableObjectStub {
+  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: Env,
-  opts: { name: string; input?: unknown; tenant?: string; roles?: string[] },
+  opts: { name: string; input?: unknown; tenant?: string; roles?: string[]; partition?: string },
 ): Promise<Response> {
   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 ?? {}),
@@ -164,28 +176,33 @@ export function makeWorker(app: PramenApp) {
       if (qToken && !h.get("authorization")) h.set("authorization", `Bearer ${qToken}`);
       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") {
       if (!isAdmin(identity)) return forbidden("recover");
-      const body = (await request.json().catch(() => ({}))) as { tenant?: unknown; timestamp?: unknown };
+      const body = (await request.json().catch(() => ({}))) as { tenant?: unknown; timestamp?: unknown; partition?: unknown };
       if (typeof body.tenant !== "string" || !body.tenant) 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);
@@ -195,8 +212,11 @@ export function makeWorker(app: PramenApp) {
     if (url.pathname === "/admin/schema") {
       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);
     }
 
@@ -205,13 +225,14 @@ export function makeWorker(app: PramenApp) {
     // in the DO under SYSTEM scope (ACL bypassed) — gated to admins here. ---
     if (url.pathname === "/admin/data" && request.method === "POST") {
       if (!isAdmin(identity)) return forbidden("data");
-      const body = (await request.json().catch(() => ({}))) as { tenant?: unknown };
+      const body = (await request.json().catch(() => ({}))) as { tenant?: unknown; partition?: unknown };
       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),
         }),
       );
@@ -225,8 +246,9 @@ export function makeWorker(app: PramenApp) {
       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",
+          "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" } },
       );
     }
@@ -259,12 +281,24 @@ export function makeWorker(app: PramenApp) {
       }
     }
 
+    // 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: string;
+    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 as Identity));
     else headers.delete("x-pramen-identity");
+    headers.set("x-pramen-partition", partition);
 
-    const stub = env.PRAMEN.get(env.PRAMEN.idFromName(tenant));
+    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);