@pramen/server 0.0.1

package/src/runtime/read-engine.ts

@@ -0,0 +1,243 @@
+// Read engine — compiles a structured query into parameterized SQL. The "no
+// hand-written SQL in handler code" property is preserved; the long-term plan is
+// to compile this module to WASM so the hot path leaves JS entirely.
+//
+// A small boolean expression AST (SqlExpr) lets user predicates (with operators,
+// AND/OR groups) and ACL row-level scopes be merged before compilation. Column
+// names come from developer code (schema keys); values are always parameterized.
+
+import type { Dialect } from "./driver";
+
+// In-process value coercion for evalExpr (SQLite-style booleans). SQL-side encoding
+// goes through the active Dialect; this mirrors it for the cell-ACL `when` evaluator.
+function bind(v: unknown): unknown {
+  return typeof v === "boolean" ? (v ? 1 : 0) : v;
+}
+
+export type CmpOp = "=" | "!=" | ">" | ">=" | "<" | "<=" | "LIKE";
+
+export type SqlExpr =
+  | { t: "true" }
+  | { t: "false" }
+  | { t: "cmp"; op: CmpOp; col: string; value: unknown }
+  | { t: "in"; col: string; values: unknown[]; negate: boolean }
+  | { t: "null"; col: string; negate: boolean }
+  | { t: "and"; parts: SqlExpr[] }
+  | { t: "or"; parts: SqlExpr[] };
+
+export const TRUE: SqlExpr = { t: "true" };
+export const FALSE: SqlExpr = { t: "false" };
+export const cmp = (op: CmpOp, col: string, value: unknown): SqlExpr => ({ t: "cmp", op, col, value });
+export const isNull = (col: string, negate = false): SqlExpr => ({ t: "null", col, negate });
+export const inList = (col: string, values: unknown[], negate = false): SqlExpr => ({ t: "in", col, values, negate });
+export const and = (...parts: SqlExpr[]): SqlExpr => ({ t: "and", parts });
+export const or = (...parts: SqlExpr[]): SqlExpr => ({ t: "or", parts });
+
+/** Equality (null -> IS NULL). Used by ACL scope building and relation loads. */
+export const eq = (col: string, value: unknown): SqlExpr => (value === null ? isNull(col) : cmp("=", col, value));
+
+/** Compile a structured user predicate into a SqlExpr.
+ * Shapes: { col: value } (eq) | { col: { gt, lt, in, like, isNull, … } } | { AND: [...] } | { OR: [...] } */
+export function compileWhere(input: Record<string, unknown>): SqlExpr {
+  const parts: SqlExpr[] = [];
+  for (const [k, v] of Object.entries(input)) {
+    if (k === "AND") {
+      parts.push(and(...(v as Record<string, unknown>[]).map(compileWhere)));
+    } else if (k === "OR") {
+      parts.push(or(...(v as Record<string, unknown>[]).map(compileWhere)));
+    } else {
+      parts.push(columnPredicate(k, v));
+    }
+  }
+  return parts.length ? and(...parts) : TRUE;
+}
+
+function columnPredicate(col: string, v: unknown): SqlExpr {
+  if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+    const ops: SqlExpr[] = [];
+    for (const [op, val] of Object.entries(v as Record<string, unknown>)) {
+      switch (op) {
+        case "eq": ops.push(eq(col, val)); break;
+        case "ne": ops.push(val === null ? isNull(col, true) : cmp("!=", col, val)); break;
+        case "gt": ops.push(cmp(">", col, val)); break;
+        case "gte": ops.push(cmp(">=", col, val)); break;
+        case "lt": ops.push(cmp("<", col, val)); break;
+        case "lte": ops.push(cmp("<=", col, val)); break;
+        case "like": ops.push(cmp("LIKE", col, val)); break;
+        case "in": ops.push(inList(col, val as unknown[])); break;
+        case "notIn": ops.push(inList(col, val as unknown[], true)); break;
+        case "isNull": ops.push(isNull(col, !val)); break; // isNull:true => IS NULL
+        default: throw new Error(`unknown operator: ${op}`);
+      }
+    }
+    return ops.length ? and(...ops) : TRUE;
+  }
+  return eq(col, v);
+}
+
+export interface CompiledSql {
+  readonly sql: string;
+  readonly params: unknown[];
+}
+
+export function compileExpr(expr: SqlExpr, dialect: Dialect, params: unknown[] = []): CompiledSql {
+  switch (expr.t) {
+    case "true":
+      return { sql: "1", params };
+    case "false":
+      return { sql: "0", params };
+    case "cmp":
+      if (expr.value === null) return { sql: `${dialect.id(expr.col)} IS NULL`, params };
+      params.push(dialect.encode(expr.value));
+      return { sql: `${dialect.id(expr.col)} ${expr.op} ${dialect.placeholder(params.length)}`, params };
+    case "null":
+      return { sql: `${dialect.id(expr.col)} IS ${expr.negate ? "NOT " : ""}NULL`, params };
+    case "in": {
+      if (expr.values.length === 0) return { sql: expr.negate ? "1" : "0", params }; // empty: notIn=>all, in=>none
+      const ph = expr.values.map((v) => (params.push(dialect.encode(v)), dialect.placeholder(params.length))).join(", ");
+      return { sql: `${dialect.id(expr.col)} ${expr.negate ? "NOT IN" : "IN"} (${ph})`, params };
+    }
+    case "and":
+    case "or": {
+      if (expr.parts.length === 0) return { sql: expr.t === "and" ? "1" : "0", params };
+      const sep = expr.t === "and" ? " AND " : " OR ";
+      const sql = expr.parts.map((p) => compileExpr(p, dialect, params).sql).join(sep);
+      return { sql: expr.parts.length > 1 ? `(${sql})` : sql, params };
+    }
+  }
+}
+
+// SQL LIKE -> RegExp. `%` is any run, `_` is any single char; SQLite LIKE is
+// case-insensitive for ASCII, so the regex is too. Other chars are escaped.
+function likeToRegex(pattern: string): RegExp {
+  let re = "";
+  for (const ch of pattern) {
+    if (ch === "%") re += ".*";
+    else if (ch === "_") re += ".";
+    else re += ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${re}$`, "is");
+}
+
+/** Evaluate a compiled predicate against an in-memory row. Mirrors compileExpr's
+ * semantics (bound-boolean coercion, NULL compares false, empty-IN, LIKE) so the
+ * declarative cell-ACL `when` path can decide per-row field visibility without a
+ * round-trip to SQLite. */
+export function evalExpr(expr: SqlExpr, row: Record<string, unknown>): boolean {
+  switch (expr.t) {
+    case "true":
+      return true;
+    case "false":
+      return false;
+    case "cmp": {
+      const left = bind(row[expr.col]);
+      if (expr.value === null) return left === null || left === undefined;
+      if (left === null || left === undefined) return false; // NULL compared to a value -> false
+      const right = bind(expr.value);
+      switch (expr.op) {
+        case "=": return left === right;
+        case "!=": return left !== right;
+        case ">": return (left as never) > (right as never);
+        case ">=": return (left as never) >= (right as never);
+        case "<": return (left as never) < (right as never);
+        case "<=": return (left as never) <= (right as never);
+        case "LIKE": return typeof left === "string" && likeToRegex(String(right)).test(left);
+      }
+      return false;
+    }
+    case "null": {
+      const v = row[expr.col];
+      const isNullVal = v === null || v === undefined;
+      return expr.negate ? !isNullVal : isNullVal;
+    }
+    case "in": {
+      const left = bind(row[expr.col]);
+      if (left === null || left === undefined) return false; // can't demonstrate membership
+      if (expr.values.length === 0) return expr.negate; // empty: notIn=>all, in=>none
+      const found = expr.values.some((v) => bind(v) === left);
+      return expr.negate ? !found : found;
+    }
+    case "and":
+      return expr.parts.every((p) => evalExpr(p, row));
+    case "or":
+      return expr.parts.some((p) => evalExpr(p, row));
+  }
+}
+
+export interface OrderBy {
+  column: string;
+  dir?: "asc" | "desc";
+}
+
+export interface QuerySpec {
+  readonly from: string;
+  readonly where?: SqlExpr;
+  readonly orderBy?: OrderBy[];
+  readonly limit?: number;
+  readonly offset?: number;
+}
+
+export type AggFn = "count" | "sum" | "avg" | "min" | "max";
+const AGG_SQL: Record<AggFn, string> = { count: "COUNT", sum: "SUM", avg: "AVG", min: "MIN", max: "MAX" };
+
+export function compileCount(from: string, dialect: Dialect, where?: SqlExpr): CompiledSql {
+  const params: unknown[] = [];
+  let sql = `SELECT COUNT(*) AS n FROM ${dialect.id(from)}`;
+  if (where && where.t !== "true") sql += ` WHERE ${compileExpr(where, dialect, params).sql}`;
+  return { sql, params };
+}
+
+export interface Aggregation {
+  fn: AggFn;
+  column?: string;
+}
+
+export function compileAggregate(
+  spec: {
+    from: string;
+    where?: SqlExpr;
+    groupBy?: string[];
+    aggregations: Record<string, Aggregation>;
+  },
+  dialect: Dialect,
+): CompiledSql {
+  const params: unknown[] = [];
+  const cols: string[] = [];
+  for (const g of spec.groupBy ?? []) cols.push(dialect.id(g));
+  for (const [key, agg] of Object.entries(spec.aggregations)) {
+    const target = agg.column != null ? dialect.id(agg.column) : "*";
+    cols.push(`${AGG_SQL[agg.fn]}(${target}) AS ${dialect.id(key)}`);
+  }
+  let sql = `SELECT ${cols.join(", ")} FROM ${dialect.id(spec.from)}`;
+  if (spec.where && spec.where.t !== "true") sql += ` WHERE ${compileExpr(spec.where, dialect, params).sql}`;
+  if (spec.groupBy && spec.groupBy.length > 0) sql += ` GROUP BY ${spec.groupBy.map((g) => dialect.id(g)).join(", ")}`;
+  return { sql, params };
+}
+
+export function compileSelect(spec: QuerySpec, dialect: Dialect): CompiledSql {
+  const params: unknown[] = [];
+  let sql = `SELECT * FROM ${dialect.id(spec.from)}`;
+
+  if (spec.where && spec.where.t !== "true") {
+    const { sql: where } = compileExpr(spec.where, dialect, params);
+    sql += ` WHERE ${where}`;
+  }
+
+  if (spec.orderBy && spec.orderBy.length > 0) {
+    const cols = spec.orderBy.map((o) => `${dialect.id(o.column)} ${o.dir === "desc" ? "DESC" : "ASC"}`);
+    sql += ` ORDER BY ${cols.join(", ")}`;
+  }
+
+  if (spec.limit != null) {
+    params.push(spec.limit);
+    sql += ` LIMIT ${dialect.placeholder(params.length)}`;
+  } else if (spec.offset != null) {
+    sql += " LIMIT -1"; // SQLite requires a LIMIT before OFFSET (offset-only is a SQLite-ism)
+  }
+  if (spec.offset != null) {
+    params.push(spec.offset);
+    sql += ` OFFSET ${dialect.placeholder(params.length)}`;
+  }
+
+  return { sql, params };
+}

package/src/runtime/schema-diff.ts

@@ -0,0 +1,57 @@
+// Schema shape + diff — powers the CLI's `schema diff`. migrate() applies every
+// change on the next DO boot, additive AND destructive. A diff classifies each as
+// `destructive` (drop / type change — rebuilds the table and CAN lose data) or not
+// (add table/column — no data loss). A rename can't be detected from a shape diff;
+// it shows as drop+add unless declared with `renamedFrom` in the schema.
+
+import type { FieldDef, SchemaDef } from "../sdk/schema";
+
+/** table -> column -> field type. The comparable surface of a schema. */
+export type SchemaShape = Record<string, Record<string, string>>;
+
+export function schemaShape(schema: SchemaDef): SchemaShape {
+  const out: SchemaShape = {};
+  for (const [table, def] of Object.entries(schema)) {
+    const cols: Record<string, string> = {};
+    for (const [col, f] of Object.entries(def.fields)) cols[col] = (f as FieldDef).type;
+    out[table] = cols;
+  }
+  return out;
+}
+
+export interface SchemaChange {
+  kind: "add-table" | "drop-table" | "add-column" | "drop-column" | "change-type";
+  table: string;
+  column?: string;
+  detail?: string;
+  /** true = rebuilds the table and may lose data (drop / type change); false =
+   * additive, no data loss. All changes are auto-applied on the next DO boot. */
+  destructive: boolean;
+}
+
+export function diffSchemaShape(prev: SchemaShape, next: SchemaShape): SchemaChange[] {
+  const changes: SchemaChange[] = [];
+
+  for (const table of Object.keys(next)) {
+    if (!(table in prev)) {
+      changes.push({ kind: "add-table", table, destructive: false });
+      continue;
+    }
+    for (const col of Object.keys(next[table]!)) {
+      if (!(col in prev[table]!)) {
+        changes.push({ kind: "add-column", table, column: col, destructive: false });
+      } else if (prev[table]![col] !== next[table]![col]) {
+        changes.push({ kind: "change-type", table, column: col, detail: `${prev[table]![col]} → ${next[table]![col]}`, destructive: true });
+      }
+    }
+    for (const col of Object.keys(prev[table]!)) {
+      if (!(col in next[table]!)) changes.push({ kind: "drop-column", table, column: col, destructive: true });
+    }
+  }
+
+  for (const table of Object.keys(prev)) {
+    if (!(table in next)) changes.push({ kind: "drop-table", table, destructive: true });
+  }
+
+  return changes;
+}

package/src/sdk/acl.ts

@@ -0,0 +1,196 @@
+// ACL primitives — the portable definition layer: role(), policy(), allow(),
+// deny(), $identity(). Resolution semantics live in runtime/acl.ts.
+//
+// Model: an Identity carries one or more roles. A policy grants a (role) access
+// to an (entity, action), optionally restricted by a row-level `where` predicate
+// and/or a set of permitted `fields`. Access is deny-by-default; policies only
+// ever grant. Across the identity's roles, grants OR-merge (any role can allow).
+
+export type Action = "read" | "create" | "update" | "delete";
+
+/** Runtime identity. Augment with your own properties (userId, tier, …). */
+export interface Identity {
+  role?: string;
+  roles?: string[];
+  [key: string]: unknown;
+}
+
+// --- $identity markers: reference an identity property inside a where rule ---
+
+const IDENTITY_MARKER = Symbol.for("pramen.identityMarker");
+
+export interface IdentityMarker {
+  readonly [IDENTITY_MARKER]: true;
+  readonly path: string;
+}
+
+/** Reference an identity property in a policy `where`, resolved per request. */
+export function $identity(path: string): IdentityMarker {
+  return { [IDENTITY_MARKER]: true, path };
+}
+
+export function isIdentityMarker(v: unknown): v is IdentityMarker {
+  return typeof v === "object" && v !== null && (v as Record<symbol, unknown>)[IDENTITY_MARKER] === true;
+}
+
+// --- $input markers: reference a request-input field inside a where rule, for a
+// capability / by-unguessable-key grant (possessing the value IS the authorization).
+
+const INPUT_MARKER = Symbol.for("pramen.inputMarker");
+
+export interface InputMarker {
+  readonly [INPUT_MARKER]: true;
+  readonly path: string;
+}
+
+/** Reference a request-input field in a policy `where`, resolved per request. The
+ * grant matches only the row(s) whose column equals the supplied value — so a
+ * caller can read a row only by presenting its unguessable key, without being able
+ * to enumerate. An absent input value makes the rule match nothing (safe deny). */
+export function $input(path: string): InputMarker {
+  return { [INPUT_MARKER]: true, path };
+}
+
+export function isInputMarker(v: unknown): v is InputMarker {
+  return typeof v === "object" && v !== null && (v as Record<symbol, unknown>)[INPUT_MARKER] === true;
+}
+
+// --- allow / deny markers ---
+
+export interface AllowMarker {
+  readonly kind: "allow";
+}
+export interface DenyMarker {
+  readonly kind: "deny";
+}
+
+export function allow(): AllowMarker {
+  return { kind: "allow" };
+}
+export function deny(): DenyMarker {
+  return { kind: "deny" };
+}
+
+// --- policy rules ---
+
+/** A where rule: column -> value, where value may be a literal or an $identity marker. */
+export type WhereRule = Record<string, unknown | IdentityMarker>;
+
+/** A per-row (cell-level) field grant: `fields` are permitted only for rows that
+ * match `when`. Additive over the policy's flat `fields` — a conditional grant can
+ * only ever ADD fields, never remove them. */
+export interface ConditionalFields {
+  fields: string[];
+  /** Row-predicate, same surface as `where` (operators, AND/OR, $identity markers). */
+  when: WhereRule;
+}
+
+/** Escape hatch for cell-level ACL: a late per-row resolver. Given the identity and
+ * the fetched (or candidate, on write) row, returns the extra permitted fields —
+ * additive over `fields`; `null` means all fields for that row. */
+export type FieldsFn = (identity: Identity | null, row: Record<string, unknown>) => string[] | null;
+
+/** Per-relation ACL inside a parent read policy. */
+export interface RelationAclRule {
+  /** Permit traversal to the related entity via this relation even if it has no
+   * flat read grant (directAccess). */
+  directAccess?: boolean;
+  /** Extra row-level predicate applied when traversing. */
+  where?: WhereRule;
+  /** Restrict fields visible through the relation. */
+  fields?: string[];
+  /** Per-row field grants applied to traversed rows. Additive over `fields`. */
+  conditionalFields?: ConditionalFields[];
+  /** Late per-row field resolver for traversed rows. Additive over `fields`. */
+  fieldsFn?: FieldsFn;
+}
+
+/** A forced column value on write: a literal, or computed from the identity. */
+export type SetValue = unknown | ((identity: Identity | null) => unknown);
+
+/** Server-side validation on write; throw to reject. Runs on the final values. */
+export type Validator = (args: { identity: Identity | null; values: Record<string, unknown> }) => void;
+
+export interface PolicyRules {
+  /** Row-level predicate (AND of equalities). Omit/empty = all rows. */
+  where?: WhereRule;
+  /** Permitted fields. Omit = all fields. On read = projection; on write = settable columns. */
+  fields?: string[];
+  /** Cell-level (per-row) field grants applied only to rows matching `when`.
+   * Additive over `fields`. On read = projection; on write = settable columns —
+   * evaluated against the candidate (insert) or post-merge (update) row. */
+  conditionalFields?: ConditionalFields[];
+  /** Escape hatch: a late per-row field resolver. Additive over `fields`. */
+  fieldsFn?: FieldsFn;
+  /** Per-relation traversal rules (see RelationAclRule). */
+  relations?: Record<string, RelationAclRule>;
+  /** Columns forced to server-controlled values on write (override client input,
+   * bypass field restriction). E.g. `{ ownerId: (i) => i?.userId }`. */
+  set?: Record<string, SetValue>;
+  /** Server-side validation; throw to reject. Sees the final (post-`set`) values. */
+  validate?: Validator;
+}
+
+// --- dynamic resolvers: a policy whose rule is computed per request ---
+
+/** Read surface given to a resolver — runs in SYSTEM mode (bypasses ACL), so a
+ * resolver can consult the DB to decide access without recursing into itself. */
+export interface ResolverDb {
+  find(spec: {
+    from: string;
+    where?: Record<string, unknown>;
+    orderBy?: { column: string; dir?: "asc" | "desc" };
+    limit?: number;
+  }): Promise<Array<Record<string, unknown>>>;
+}
+
+export interface ResolverContext {
+  readonly identity: Identity | null;
+  readonly db: ResolverDb;
+}
+
+export type ResolverFn = (ctx: ResolverContext) => PolicyRule | Promise<PolicyRule>;
+
+export interface ResolverMarker {
+  readonly kind: "resolver";
+  readonly id: number;
+  readonly fn: ResolverFn;
+}
+
+let resolverCounter = 0;
+/** A policy rule evaluated once per request during warmup; returns allow/deny/rules. */
+export function resolve(fn: ResolverFn): ResolverMarker {
+  return { kind: "resolver", id: resolverCounter++, fn };
+}
+
+export type PolicyRule = AllowMarker | DenyMarker | PolicyRules | ResolverMarker;
+
+export interface Policy {
+  readonly name: string;
+  readonly entity: string;
+  readonly action: Action;
+  readonly rule: PolicyRule;
+}
+
+export function policy(name: string, entity: string, action: Action, rule: PolicyRule): Policy {
+  return { name, entity, action, rule };
+}
+
+export interface Role {
+  readonly name: string;
+  readonly policies: Policy[];
+}
+
+export function role(name: string, policies: Policy[]): Role {
+  return { name, policies };
+}
+
+export function isAllow(r: PolicyRule): r is AllowMarker {
+  return (r as AllowMarker).kind === "allow";
+}
+export function isDeny(r: PolicyRule): r is DenyMarker {
+  return (r as DenyMarker).kind === "deny";
+}
+export function isResolver(r: PolicyRule): r is ResolverMarker {
+  return (r as ResolverMarker).kind === "resolver";
+}

package/src/sdk/app.ts

@@ -0,0 +1,25 @@
+// createApp — binds the handler factories to a concrete schema so `ctx.db` is
+// fully typed (table names, where columns/values, row results, insert shapes).
+//
+//   const schema = defineSchema({ notes: Entity(t => ({ ... })) });
+//   const { query, mutation } = createApp(schema);
+//   const listNotes = query((ctx) => ctx.db.find({ from: "notes" })); // typed!
+
+import type { Handler, HandlerContext, HandlerOpts } from "./handlers";
+import type { SchemaDef } from "./schema";
+
+export function createApp<S extends SchemaDef>(schema: S) {
+  type Ctx = HandlerContext<S>;
+
+  const query = <I = unknown, O = unknown>(
+    run: (ctx: Ctx, input: I) => O | Promise<O>,
+    opts?: HandlerOpts<I>,
+  ): Handler<I, O> => ({ kind: "query", run: run as Handler<I, O>["run"], input: opts?.input });
+
+  const mutation = <I = unknown, O = unknown>(
+    run: (ctx: Ctx, input: I) => O | Promise<O>,
+    opts?: HandlerOpts<I>,
+  ): Handler<I, O> => ({ kind: "mutation", run: run as Handler<I, O>["run"], input: opts?.input });
+
+  return { schema, query, mutation };
+}

package/src/sdk/files.ts

@@ -0,0 +1,53 @@
+// File storage — the portable type surface. The `fileRef` column type and the
+// `ctx.files` facade handlers use. Pure types (no platform code); the Cloudflare
+// glue (R2 adapter, signing, the Worker /files endpoint) lives in runtime/storage.ts.
+
+/** What a `fileRef` column holds: small JSON metadata, never the bytes. */
+export interface FileRef {
+  /** Object-store key (tenant-scoped, e.g. "acme/ab12…"). */
+  key: string;
+  /** Size in bytes (0 until the upload is confirmed via files.head()). */
+  size: number;
+  contentType: string;
+  /** Original upload filename, used for Content-Disposition on download. */
+  filename?: string;
+  /** Epoch ms the ref was last written/confirmed. */
+  uploadedAt?: number;
+}
+
+/** Object-store metadata for a stored blob. */
+export interface HeadResult {
+  size: number;
+  contentType?: string;
+}
+
+export interface SignUploadOpts {
+  contentType: string;
+  filename?: string;
+  /** Max accepted upload size in bytes (enforced at the Worker). */
+  maxSize?: number;
+  /** URL lifetime in seconds (default 900 = 15 min). */
+  expiresIn?: number;
+  /** Optional key prefix segment under the tenant (e.g. "avatars"). */
+  prefix?: string;
+}
+
+export interface SignDownloadOpts {
+  /** URL lifetime in seconds (default 3600 = 1 hour). */
+  expiresIn?: number;
+  /** Force a download (Content-Disposition: attachment) vs inline. */
+  download?: boolean;
+}
+
+/** The per-tenant file facade handed to handlers as `ctx.files`. */
+export interface Files {
+  /** Mint a tenant-scoped key + a signed PUT url for a direct-to-store upload. */
+  signUpload(opts: SignUploadOpts): Promise<{ url: string; ref: FileRef }>;
+  /** Mint a signed GET url for an existing blob. Call only after an ACL'd read of
+   * the owning row — knowing a key is not, by itself, authorization. */
+  signDownload(ref: FileRef | string, opts?: SignDownloadOpts): Promise<{ url: string; expiresAt: number }>;
+  /** Object-store metadata (size/contentType), or null if the blob is absent. */
+  head(key: string): Promise<HeadResult | null>;
+  /** Delete a blob (lifecycle / cascade). */
+  delete(key: string): Promise<void>;
+}

package/src/sdk/handlers.ts

@@ -0,0 +1,65 @@
+// Handler factories — `query()` and `mutation()`. A query reads; a mutation is
+// wrapped in BEGIN/COMMIT by the dispatcher and
+// rolls back on throw (see runtime/dispatch.ts).
+
+import type { Db } from "../runtime/db";
+import type { Kv } from "../runtime/kv";
+import type { Identity } from "./acl";
+import type { Files } from "./files";
+import type { SchemaDef } from "./schema";
+
+export interface HandlerContext<S extends SchemaDef = SchemaDef> {
+  /** Schema-typed repository: find/insert/update/delete inferred from S. */
+  readonly db: Db<S>;
+  /** Project KV — global (cross-tenant) config/flags/cache. Not per-tenant
+   * (that's db) and not transactional. */
+  readonly kv: Kv;
+  /** Per-tenant file storage: mint signed upload/download urls, head/delete blobs.
+   * Bytes flow through the Worker /files/* route, never through the DO. */
+  readonly files: Files;
+  /** The Worker/DO environment — bindings (KV, R2, DB, …) plus vars and secrets
+   * (AUTH_SECRET, plus anything in wrangler.jsonc / .dev.vars / `wrangler secret`).
+   * Use it to call external APIs from handlers (Stripe, Resend, …). Loosely typed;
+   * cast a value at the use site, e.g. `ctx.env.STRIPE_SECRET_KEY as string`. */
+  readonly env: Readonly<Record<string, unknown>>;
+  /** Resolved identity for this request (null = anonymous). */
+  readonly identity: Identity | null;
+}
+
+export type HandlerKind = "query" | "mutation";
+
+export interface Handler<I = unknown, O = unknown> {
+  readonly kind: HandlerKind;
+  // Stored handlers are schema-agnostic; createApp() binds the typed surface.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  readonly run: (ctx: HandlerContext<any>, input: I) => O | Promise<O>;
+  /** 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;
+}
+
+export interface HandlerOpts<I> {
+  input?: (raw: unknown) => I;
+}
+
+// Standalone (schema-agnostic) handler factories. Prefer createApp(schema) for a
+// typed ctx.db; these remain for untyped/ad-hoc use.
+export function query<I = unknown, O = unknown>(
+  run: (ctx: HandlerContext, input: I) => O | Promise<O>,
+  opts?: HandlerOpts<I>,
+): Handler<I, O> {
+  return { kind: "query", run, input: opts?.input };
+}
+
+export function mutation<I = unknown, O = unknown>(
+  run: (ctx: HandlerContext, input: I) => O | Promise<O>,
+  opts?: HandlerOpts<I>,
+): Handler<I, O> {
+  return { kind: "mutation", run, input: opts?.input };
+}
+
+// Registry of handlers keyed by RPC name. Uses `any` for the per-handler input/
+// output so handlers with concrete, differing signatures remain assignable
+// (a precise union would break under contravariance).
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type HandlerMap = Record<string, Handler<any, any>>;