@pramen/server 0.0.1

package/src/runtime/dispatch.ts

@@ -0,0 +1,65 @@
+// Dispatch — resolves a handler by name and runs it with a fresh, ACL-scoped Db.
+// Mutations run inside storage.transaction(), which commits on success and rolls
+// back on throw — the platform-correct way to auto-wrap mutations in BEGIN/COMMIT.
+// (DO SQLite rejects raw BEGIN/COMMIT because it does atomic write coalescing under
+// this API.) Single-writer serialization is free:
+// a Durable Object processes one request at a time.
+//
+// The result reports `touched` (tables the run read or wrote) so the live-query
+// layer can match a mutation's writes against each subscription's reads.
+
+import { Db } from "./db";
+import { warmup, type AclContext } from "./acl";
+import { BadRequest } from "./errors";
+import type { Driver } from "./driver";
+import type { Kv } from "./kv";
+import type { Files } from "../sdk/files";
+import type { ResolverDb } from "../sdk/acl";
+import type { SchemaDef } from "../sdk/schema";
+import type { HandlerContext, HandlerKind, HandlerMap } from "../sdk/handlers";
+
+export interface DispatchResult {
+  readonly result: unknown;
+  readonly kind: HandlerKind;
+  readonly touched: string[];
+}
+
+export async function dispatch(
+  handlers: HandlerMap,
+  schema: SchemaDef,
+  driver: Driver,
+  kv: Kv,
+  files: Files,
+  env: Readonly<Record<string, unknown>>,
+  acl: AclContext,
+  name: string,
+  input: unknown,
+): Promise<DispatchResult> {
+  const handler = handlers[name];
+  if (!handler) throw new BadRequest(`unknown handler: ${name}`);
+
+  // Validate/parse the request input at the boundary, if the handler declares it.
+  let parsed = input;
+  if (handler.input) {
+    try {
+      parsed = handler.input(input);
+    } catch (e) {
+      throw new BadRequest(e instanceof Error ? e.message : "invalid input");
+    }
+  }
+
+  // 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);
+  const resolved = await warmup(acl.acl, acl.identity, systemDb as unknown as ResolverDb);
+
+  const db = new Db(driver, { acl: acl.acl, identity: acl.identity, input: parsed, resolved }, schema);
+  const ctx: HandlerContext = { db, kv, files, env, identity: acl.identity };
+
+  const result =
+    handler.kind === "query"
+      ? await handler.run(ctx, parsed)
+      : await driver.transaction(async () => handler.run(ctx, parsed));
+
+  return { result, kind: handler.kind, touched: [...db.touched] };
+}

package/src/runtime/driver.ts

@@ -0,0 +1,95 @@
+// Driver + Dialect — the substrate seam. pramen's ACL, read-engine, repository, and
+// migrator are written against these two interfaces, so the same data layer runs
+// over any SQL backend:
+//
+//   - Driver  : how to execute SQL and run a transaction (async). One per backend
+//               (DO SQLite, D1, Hyperdrive→Postgres, …).
+//   - Dialect : how a backend spells SQL (identifier quoting, bind placeholders,
+//               RETURNING support, value encoding). One per SQL flavor.
+//
+// This makes "Worker + D1" or "Worker + Hyperdrive/Postgres" a matter of plugging
+// in a Driver, rather than rewriting the engine. Live queries remain a DO-only
+// capability (they need a single writer + a stateful socket host).
+
+export type Row = Record<string, unknown>;
+
+export interface Dialect {
+  /** Render an identifier (table/column), quoting as the backend requires. */
+  id(name: string): string;
+  /** Bind placeholder for the `n`-th parameter (1-based): `?` (SQLite/MySQL) or `$n` (Postgres). */
+  placeholder(n: number): string;
+  /** Whether INSERT/UPDATE/DELETE ... RETURNING is supported (SQLite/Postgres yes; MySQL no). */
+  readonly returning: boolean;
+  /** Coerce a JS value for binding (e.g. boolean → 0/1 on SQLite). */
+  encode(v: unknown): unknown;
+}
+
+const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+// Column/table names come from developer schema keys (and validated `where` keys),
+// never raw user input — but we still guard the identifier shape before interpolating.
+function checkIdent(name: string): string {
+  if (!IDENT_RE.test(name)) throw new Error(`invalid identifier: ${name}`);
+  return name;
+}
+
+/** SQLite (DO SQLite and D1 both speak this). Bare identifiers, `?` placeholders,
+ * booleans stored as INTEGER 0/1, RETURNING supported. */
+export const sqliteDialect: Dialect = {
+  id: checkIdent,
+  placeholder: () => "?",
+  returning: true,
+  encode: (v) => (typeof v === "boolean" ? (v ? 1 : 0) : v),
+};
+
+/** Postgres (e.g. over Hyperdrive). Double-quoted identifiers preserve case (so
+ * `ownerId` doesn't fold to `ownerid`), `$n` placeholders, native booleans,
+ * RETURNING supported. */
+export const postgresDialect: Dialect = {
+  id: (name) => `"${checkIdent(name)}"`,
+  placeholder: (n) => `$${n}`,
+  returning: true,
+  encode: (v) => v, // the pg driver handles type encoding
+};
+
+export interface Driver {
+  readonly dialect: Dialect;
+  /** Run a parameterized statement and return the result rows (empty for writes
+   * without RETURNING). Params are already dialect-encoded by the caller. */
+  exec(sql: string, params: unknown[]): Promise<Row[]>;
+  /** Run `fn` inside a transaction: commit on resolve, roll back on throw. */
+  transaction<T>(fn: () => Promise<T>): Promise<T>;
+}
+
+/** DO SQLite — the in-process store. `SqlStorage` is synchronous; we wrap it as an
+ * async Driver. Transactions use the DO's atomic `transaction()`. */
+export class DoSqliteDriver implements Driver {
+  readonly dialect = sqliteDialect;
+  constructor(private readonly storage: DurableObjectStorage) {}
+
+  async exec(sql: string, params: unknown[]): Promise<Row[]> {
+    return this.storage.sql.exec(sql, ...params).toArray() as Row[];
+  }
+
+  transaction<T>(fn: () => Promise<T>): Promise<T> {
+    return this.storage.transaction(fn);
+  }
+}
+
+/** D1 — SQLite over RPC. Async by nature. D1 has no interactive transactions, so
+ * `transaction()` runs `fn` without one (a documented limitation: mutations don't
+ * roll back on throw the way they do on a DO). Use a DO when you need that. */
+export class D1Driver implements Driver {
+  readonly dialect = sqliteDialect;
+  constructor(private readonly db: D1Database) {}
+
+  async exec(sql: string, params: unknown[]): Promise<Row[]> {
+    const stmt = params.length ? this.db.prepare(sql).bind(...params) : this.db.prepare(sql);
+    const { results } = await stmt.all<Row>();
+    return results ?? [];
+  }
+
+  transaction<T>(fn: () => Promise<T>): Promise<T> {
+    return fn();
+  }
+}

package/src/runtime/errors.ts

@@ -0,0 +1,56 @@
+// Error model. Anything that is the *client's* fault carries a status + code and
+// a message safe to return. Everything else is logged server-side and surfaced as
+// a generic 500 — internal messages / stack traces never reach the client.
+
+export class PramenError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly code: string,
+  ) {
+    super(message);
+    this.name = "PramenError";
+  }
+}
+
+export class BadRequest extends PramenError {
+  constructor(message: string) {
+    super(message, 400, "bad_request");
+  }
+}
+
+/** 401 — the caller is unauthenticated (no/invalid identity). */
+export class Unauthorized extends PramenError {
+  constructor(message = "authentication required") {
+    super(message, 401, "unauthorized");
+  }
+}
+
+/** 403 — authenticated but not permitted. For handler-level checks; the Db
+ * chokepoint raises AclDenied for row/field ACL. */
+export class Forbidden extends PramenError {
+  constructor(message = "forbidden") {
+    super(message, 403, "forbidden");
+  }
+}
+
+export interface ErrorBody {
+  ok: false;
+  error: string;
+  code: string;
+}
+
+function classify(err: unknown): { status: number; body: ErrorBody } {
+  if (err instanceof PramenError) {
+    return { status: err.status, body: { ok: false, error: err.message, code: err.code } };
+  }
+  console.error("pramen: unhandled error", err);
+  return { status: 500, body: { ok: false, error: "internal error", code: "internal" } };
+}
+
+export const toResponse = classify;
+
+export function toWsError(id: string, err: unknown): { type: "error"; id: string; error: string; code: string } {
+  const { body } = classify(err);
+  return { type: "error", id, error: body.error, code: body.code };
+}

package/src/runtime/kv.ts

@@ -0,0 +1,47 @@
+// Kv — a thin, prefixed wrapper over the project's Workers KV namespace, handed
+// to handlers as ctx.kv.
+//
+// Two levels of namespacing keep things isolated:
+//  - Across projects: each project declares its own KV namespace in oblaka.ts
+//    (named per project), so projects in one account never share a namespace.
+//  - Within the namespace: keys are prefixed (`app:` for handler data) so they
+//    never collide with pramen-internal keys (the tenant registry uses `tenant:`).
+//
+// ctx.kv is GLOBAL across all tenants of the project — use it for config, feature
+// flags, and caches, NOT per-tenant data (that's ctx.db). KV is eventually
+// consistent and is NOT part of a mutation's transaction.
+
+export class Kv {
+  constructor(
+    private readonly ns: KVNamespace,
+    private readonly prefix = "app:",
+  ) {}
+
+  private full(key: string): string {
+    return this.prefix + key;
+  }
+
+  get(key: string): Promise<string | null>;
+  get(key: string, type: "json"): Promise<unknown>;
+  get(key: string, type?: "json"): Promise<string | null | unknown> {
+    return type === "json" ? this.ns.get(this.full(key), "json") : this.ns.get(this.full(key), "text");
+  }
+
+  async put(key: string, value: string, opts?: { expirationTtl?: number; expiration?: number }): Promise<void> {
+    await this.ns.put(this.full(key), value, opts);
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.ns.delete(this.full(key));
+  }
+
+  /** List keys under an (app-relative) prefix; returned names have the internal
+   * prefix stripped. cursor is null when the listing is complete. */
+  async list(opts?: { prefix?: string; limit?: number; cursor?: string }): Promise<{ keys: string[]; cursor: string | null }> {
+    const res = await this.ns.list({ prefix: this.full(opts?.prefix ?? ""), limit: opts?.limit, cursor: opts?.cursor });
+    return {
+      keys: res.keys.map((k) => k.name.slice(this.prefix.length)),
+      cursor: res.list_complete ? null : ((res as { cursor?: string }).cursor ?? null),
+    };
+  }
+}

package/src/runtime/migrate.ts

@@ -0,0 +1,193 @@
+// Schema migration — applied on boot, wrapped in a transaction by the caller.
+// Runs over a Driver, so it works on any SQLite-flavored substrate (DO SQLite and
+// D1). The introspection (`PRAGMA table_info`, `sqlite_master`) and table-rebuild
+// are SQLite-specific; a Postgres/MySQL migrator would be a separate adapter.
+// Reconciles the live store with the declared schema in two passes:
+//   1. additive (no data loss): missing table -> CREATE TABLE; missing column ->
+//      ALTER TABLE ADD COLUMN (nullable).
+//   2. destructive: a live column the schema no longer declares is DROPPED, a type
+//      change is applied, and a `renamedFrom` column is renamed — all via the
+//      standard SQLite table-rebuild (create new, copy, drop old, rename). This is
+//      auto-applied: a bad deploy CAN lose data, by design (WIP, no backward-compat).
+//
+// A schema hash in the internal `_pramen_meta` table lets an unchanged schema skip
+// introspection entirely on warm boots. The live table (PRAGMA) is the ground
+// truth diffed against the schema — no stored shape needed.
+//
+// ADD COLUMN is always nullable (SQLite can't add NOT NULL to a populated table).
+// A rename can't be inferred from a diff (a removed + added column is ambiguous),
+// 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 type { Driver } from "./driver";
+import type { EntityFields, FieldDef, SchemaDef } from "../sdk/schema";
+
+export interface MigrationReport {
+  changed: boolean;
+  created: string[];
+  added: string[];
+  /** Tables rebuilt to apply a drop / rename / type change. */
+  rebuilt: string[];
+  /** Tables dropped because the schema no longer declares them. */
+  droppedTables: string[];
+  /** Destructive ops detected but NOT applied because destructive migrations are
+   * disabled (the default). Re-deploy with allowDestructive to apply them. */
+  skipped: string[];
+}
+
+export interface MigrateOptions {
+  /** Apply destructive changes (drop/rebuild/type-change/table-drop). Off by default
+   * — 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;
+}
+
+/** 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. */
+function isInternalTable(name: string): boolean {
+  const n = name.toLowerCase();
+  return (
+    n.startsWith("_pramen") ||
+    n.startsWith("__pramen") ||
+    n.startsWith("sqlite_") ||
+    n.startsWith("_cf_") ||
+    n.startsWith("d1_")
+  );
+}
+
+function ident(name: string): string {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new Error(`invalid identifier: ${name}`);
+  return name;
+}
+
+export function schemaHash(schema: SchemaDef): string {
+  const canon: Record<string, unknown> = {};
+  for (const [table, def] of Object.entries(schema)) canon[table] = def.fields;
+  return digest(canon);
+}
+
+/** Live columns of a table -> their declared SQL type (uppercased). Empty if the
+ * table doesn't exist. */
+async function tableColumns(driver: Driver, table: string): Promise<Map<string, string>> {
+  const rows = (await driver.exec(`PRAGMA table_info(${ident(table)})`, [])) as { name: string; type: string }[];
+  return new Map(rows.map((r) => [r.name, (r.type || "").toUpperCase()]));
+}
+
+async function readMeta(driver: Driver, key: string): Promise<string | undefined> {
+  const rows = (await driver.exec(`SELECT value FROM _pramen_meta WHERE key = ?`, [key])) as { value: string }[];
+  return rows[0]?.value;
+}
+
+async function writeMeta(driver: Driver, key: string, value: string): Promise<void> {
+  await driver.exec(`INSERT OR REPLACE INTO _pramen_meta (key, value) VALUES (?, ?)`, [key, value]);
+}
+
+/** Rebuild a table to exactly the declared schema: create a temp table, copy each
+ * desired column from its source (renamed or same-named live column, CAST on a
+ * type change; brand-new columns left NULL), drop the old table, rename the temp. */
+async function rebuildTable(driver: Driver, table: string, def: { fields: EntityFields }, live: Map<string, string>): Promise<void> {
+  const tmp = `__pramen_rebuild_${table}`;
+  await driver.exec(`DROP TABLE IF EXISTS ${ident(tmp)}`, []);
+  await driver.exec(createTableSql(tmp, def), []);
+
+  const destCols: string[] = [];
+  const srcExprs: string[] = [];
+  for (const [name, field] of Object.entries(def.fields)) {
+    const f = field as FieldDef;
+    const src = f.renamedFrom && live.has(f.renamedFrom) ? f.renamedFrom : live.has(name) ? name : undefined;
+    if (!src) continue; // brand-new column with no source -> leave NULL
+    const target = sqlType(f);
+    destCols.push(ident(name));
+    srcExprs.push(live.get(src) === target ? ident(src) : `CAST(${ident(src)} AS ${target})`);
+  }
+  if (destCols.length > 0) {
+    await driver.exec(`INSERT INTO ${ident(tmp)} (${destCols.join(", ")}) SELECT ${srcExprs.join(", ")} FROM ${ident(table)}`, []);
+  }
+  await driver.exec(`DROP TABLE ${ident(table)}`, []);
+  await driver.exec(`ALTER TABLE ${ident(tmp)} RENAME TO ${ident(table)}`, []);
+}
+
+export async function migrate(driver: Driver, schema: SchemaDef, opts: MigrateOptions = {}): Promise<MigrationReport> {
+  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)
+    return { changed: false, created: [], added: [], rebuilt: [], droppedTables: [], skipped: [] };
+
+  const created: string[] = [];
+  const added: string[] = [];
+  const rebuilt: string[] = [];
+  const droppedTables: string[] = [];
+  const skipped: string[] = [];
+
+  for (const [table, def] of Object.entries(schema)) {
+    const existing = await tableColumns(driver, table);
+    if (existing.size === 0) {
+      await driver.exec(createTableSql(table, def), []);
+      created.push(table);
+      continue;
+    }
+    // Pass 1 — additive: add any column the schema declares but the table lacks.
+    for (const [name, field] of Object.entries(def.fields)) {
+      if (existing.has(name)) continue;
+      await driver.exec(`ALTER TABLE ${ident(table)} ADD COLUMN ${addColumnSql(name, field as FieldDef)}`, []);
+      added.push(`${table}.${name}`);
+    }
+
+    // Pass 2 — destructive: rebuild if any live column must be dropped, a declared
+    // column changed type, or a rename hint points at an existing live column.
+    const live = await tableColumns(driver, table); // re-read (now includes additively-added columns)
+    const desired = new Set(Object.keys(def.fields));
+    const renamedSources = new Set<string>();
+    for (const f of Object.values(def.fields)) {
+      const from = (f as FieldDef).renamedFrom;
+      if (from && live.has(from)) renamedSources.add(from);
+    }
+    const needsDrop = [...live.keys()].some((c) => !desired.has(c) && !renamedSources.has(c));
+    const needsTypeChange = Object.entries(def.fields).some(
+      ([n, f]) => live.has(n) && live.get(n) !== sqlType(f as FieldDef),
+    );
+    if (needsDrop || needsTypeChange || renamedSources.size > 0) {
+      if (allowDestructive) {
+        await rebuildTable(driver, table, def, live);
+        rebuilt.push(table);
+      } else {
+        skipped.push(`rebuild ${table} (drop/type-change/rename)`);
+      }
+    }
+  }
+
+  // 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 stmt of indexStatements(table, def)) await driver.exec(stmt, []);
+  }
+
+  // Drop tables the schema no longer declares (internal bookkeeping tables skipped).
+  const liveTables = (await driver.exec(`SELECT name FROM sqlite_master WHERE type = 'table'`, [])) as { name: string }[];
+  for (const { name } of liveTables) {
+    if (isInternalTable(name) || name in schema) continue;
+    if (allowDestructive) {
+      await driver.exec(`DROP TABLE ${ident(name)}`, []);
+      droppedTables.push(name);
+    } else {
+      skipped.push(`drop table ${name}`);
+    }
+  }
+
+  // Only record the schema as applied when fully reconciled. If destructive changes
+  // 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);
+  } else {
+    console.warn(
+      `pramen: ${skipped.length} destructive migration(s) skipped (set PRAMEN_ALLOW_DESTRUCTIVE=true to apply): ${skipped.join("; ")}`,
+    );
+  }
+  return { changed: true, created, added, rebuilt, droppedTables, skipped };
+}

package/src/runtime/protocol.ts

@@ -0,0 +1,46 @@
+// Live-query wire protocol (JSON over WebSocket).
+//
+// Client -> server:
+//   { type: "subscribe",   id, name, input? }   // query handler; initial data + pushes
+//   { type: "unsubscribe", id }
+//   { type: "call",        id, name, input? }    // one-shot any handler (query or mutation)
+//
+// Server -> client:
+//   { type: "data",   id, result }   // initial subscription result + every update
+//   { type: "result", id, result }   // reply to a one-shot call
+//   { type: "error",  id, error }
+
+export interface SubscribeMsg {
+  type: "subscribe";
+  id: string;
+  name: string;
+  input?: unknown;
+}
+export interface UnsubscribeMsg {
+  type: "unsubscribe";
+  id: string;
+}
+export interface CallMsg {
+  type: "call";
+  id: string;
+  name: string;
+  input?: unknown;
+}
+
+export type ClientMsg = SubscribeMsg | UnsubscribeMsg | CallMsg;
+
+export type ServerMsg =
+  | { type: "data"; id: string; result: unknown }
+  | { type: "result"; id: string; result: unknown }
+  | { type: "error"; id: string; error: string };
+
+/** A live subscription, persisted on the socket so it survives DO hibernation. */
+export interface Subscription {
+  id: string;
+  name: string;
+  input: unknown;
+  /** Tables the query read — the coarse prefilter for which writes might matter. */
+  tables: string[];
+  /** Digest of the last result pushed — used to suppress no-op (row-level) pushes. */
+  digest: string;
+}