@pylonsync/functions 0.2.4

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@pylonsync/functions",
+  "version": "0.2.4",
+  "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./runtime": "./src/runtime.ts"
+  },
+  "bin": {
+    "pylon-functions-runtime": "src/runtime.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc"
+  },
+  "keywords": [
+    "pylon",
+    "typescript",
+    "functions",
+    "database"
+  ],
+  "license": "MIT OR Apache-2.0",
+  "devDependencies": {
+    "typescript": "^5.5"
+  },
+  "peerDependencies": {
+    "bun-types": "*"
+  },
+  "peerDependenciesMeta": {
+    "bun-types": {
+      "optional": true
+    }
+  }
+}

package/src/define.ts

@@ -0,0 +1,109 @@
+/**
+ * Function definition constructors.
+ *
+ * These are the primary API for defining server-side functions.
+ */
+
+import type {
+  FnDefinition,
+  QueryCtx,
+  MutationCtx,
+  ActionCtx,
+  Validator,
+} from "./types";
+
+interface QueryDef<TArgs, TReturn> {
+  args?: Record<string, Validator>;
+  handler: (ctx: QueryCtx, args: TArgs) => Promise<TReturn>;
+}
+
+interface MutationDef<TArgs, TReturn> {
+  args?: Record<string, Validator>;
+  handler: (ctx: MutationCtx, args: TArgs) => Promise<TReturn>;
+}
+
+interface ActionDef<TArgs, TReturn> {
+  args?: Record<string, Validator>;
+  handler: (ctx: ActionCtx, args: TArgs) => Promise<TReturn>;
+}
+
+/**
+ * Define a read-only query function.
+ *
+ * Queries use the read pool — they never block writes and can run
+ * concurrently. They cannot modify data.
+ *
+ * @example
+ * ```typescript
+ * export default query({
+ *   args: { auctionId: v.string() },
+ *   async handler(ctx, args) {
+ *     return ctx.db.query("Lot", {
+ *       auctionId: args.auctionId,
+ *       $order: { closesAt: "asc" },
+ *     });
+ *   },
+ * });
+ * ```
+ */
+export function query<TArgs = Record<string, unknown>, TReturn = unknown>(
+  def: QueryDef<TArgs, TReturn>
+): FnDefinition<TArgs, TReturn> {
+  return { type: "query", args: def.args, handler: def.handler };
+}
+
+/**
+ * Define a transactional mutation function.
+ *
+ * The entire handler IS the transaction. If it returns, all writes commit
+ * atomically. If it throws, all writes roll back — including scheduled
+ * functions.
+ *
+ * Mutations can stream data to the client via `ctx.stream.write()`.
+ * Stream chunks are sent immediately; DB writes commit at the end.
+ *
+ * @example
+ * ```typescript
+ * export default mutation({
+ *   args: { lotId: v.string(), amount: v.number() },
+ *   async handler(ctx, args) {
+ *     const lot = await ctx.db.get("Lot", args.lotId);
+ *     if (!lot) throw ctx.error("NOT_FOUND", "Lot not found");
+ *     await ctx.db.insert("Bid", { lotId: args.lotId, amount: args.amount });
+ *     return { accepted: true };
+ *   },
+ * });
+ * ```
+ */
+export function mutation<TArgs = Record<string, unknown>, TReturn = unknown>(
+  def: MutationDef<TArgs, TReturn>
+): FnDefinition<TArgs, TReturn> {
+  return { type: "mutation", args: def.args, handler: def.handler };
+}
+
+/**
+ * Define an action function (external I/O allowed).
+ *
+ * Actions can call external APIs (fetch, email, Stripe, etc.) but cannot
+ * access the database directly. Use `ctx.runQuery()` and `ctx.runMutation()`
+ * for DB access — each runs in its own transaction.
+ *
+ * Actions are NOT automatically retried because they may have side effects.
+ *
+ * @example
+ * ```typescript
+ * export default action({
+ *   args: { lotId: v.string() },
+ *   async handler(ctx, args) {
+ *     const lot = await ctx.runQuery("lotDetails", { lotId: args.lotId });
+ *     await fetch("https://api.sendgrid.com/...", { ... });
+ *     await ctx.runMutation("markNotified", { lotId: args.lotId });
+ *   },
+ * });
+ * ```
+ */
+export function action<TArgs = Record<string, unknown>, TReturn = unknown>(
+  def: ActionDef<TArgs, TReturn>
+): FnDefinition<TArgs, TReturn> {
+  return { type: "action", args: def.args, handler: def.handler };
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * @pylonsync/functions — TypeScript function definitions for pylon.
+ *
+ * This is the developer-facing API. App developers import from here
+ * to define queries, mutations, and actions.
+ *
+ * @example
+ * ```typescript
+ * import { mutation, v } from "@pylonsync/functions";
+ *
+ * export default mutation({
+ *   args: { lotId: v.string(), amount: v.number() },
+ *   async handler(ctx, args) {
+ *     const lot = await ctx.db.get("Lot", args.lotId);
+ *     // ...
+ *   },
+ * });
+ * ```
+ */
+
+export { query, mutation, action } from "./define";
+export { v } from "./validators";
+export { resetDb, installTestIsolation } from "./testing";
+export type {
+  QueryCtx,
+  MutationCtx,
+  ActionCtx,
+  DbReader,
+  DbWriter,
+  Stream,
+  Scheduler,
+  AuthInfo,
+  FnDefinition,
+} from "./types";

package/src/runtime.ts

@@ -0,0 +1,668 @@
+/**
+ * Function runtime — the Bun process that loads and executes TypeScript functions.
+ *
+ * Protocol: NDJSON over stdin/stdout.
+ *
+ * Usage:
+ *   bun run packages/functions/src/runtime.ts ./functions
+ *
+ * Design:
+ * - A single reader consumes lines from stdin and dispatches by message type.
+ * - Incoming `call` messages launch a handler.
+ * - Incoming `result` messages resolve a pending RPC keyed by call_id.
+ * - Each call's handler has at most ONE outstanding RPC at a time (it awaits
+ *   each ctx.db / ctx.scheduler / ctx.runMutation call), so the map never
+ *   needs to queue multiple RPCs per call_id.
+ */
+
+import type {
+  DbReader,
+  DbWriter,
+  Stream,
+  Scheduler,
+  QueryCtx,
+  MutationCtx,
+  ActionCtx,
+  FnDefinition,
+  AuthInfo,
+} from "./types";
+import { validateArgs } from "./validators";
+import { readdirSync } from "fs";
+import { join, basename } from "path";
+
+// ---------------------------------------------------------------------------
+// Protocol types
+// ---------------------------------------------------------------------------
+
+interface CallMessage {
+  type: "call";
+  call_id: string;
+  fn_name: string;
+  fn_type: "query" | "mutation" | "action";
+  args: Record<string, unknown>;
+  auth: AuthInfo;
+}
+
+interface ResultMessage {
+  type: "result";
+  call_id: string;
+  data?: unknown;
+  error?: { code: string; message: string };
+}
+
+// ---------------------------------------------------------------------------
+// Send
+// ---------------------------------------------------------------------------
+
+function send(msg: Record<string, unknown>): void {
+  const line = JSON.stringify(msg) + "\n";
+  Bun.write(Bun.stdout, line);
+}
+
+/**
+ * Redirect console.* from user code to stderr so handlers can't accidentally
+ * emit a line that looks like a protocol frame and confuse the Rust reader.
+ *
+ * Before this guard, a handler calling `console.log('{"type":"return",...}')`
+ * — either intentionally or by logging an object shaped that way — would be
+ * parsed by the host as a real protocol message. Moving all console output
+ * to stderr keeps stdout reserved for NDJSON protocol frames only.
+ *
+ * The original console methods are saved on the console object as
+ * `__stdoutLog` etc. in case the runtime itself needs to write diagnostics
+ * to stdout for some reason (it currently doesn't).
+ */
+function fenceStdout(): void {
+  const toStderr = (prefix: string) => (...args: unknown[]) => {
+    const line = args
+      .map((a) => {
+        if (typeof a === "string") return a;
+        try {
+          return JSON.stringify(a);
+        } catch {
+          return String(a);
+        }
+      })
+      .join(" ");
+    Bun.write(Bun.stderr, `${prefix}${line}\n`);
+  };
+  // Intentional: we want console.* for user handlers to go to stderr.
+  // Overwrite the globals before any user code is loaded.
+  const c = globalThis.console as unknown as Record<string, unknown>;
+  c.__stdoutLog = c.log;
+  c.log = toStderr("");
+  c.info = toStderr("");
+  c.warn = toStderr("[warn] ");
+  c.error = toStderr("[error] ");
+  c.debug = toStderr("[debug] ");
+}
+
+// ---------------------------------------------------------------------------
+// Single reader + dispatcher
+// ---------------------------------------------------------------------------
+
+/**
+ * Pending RPCs keyed by op_id (with a fallback to call_id for legacy hosts
+ * that don't echo op_id). Each in-flight host → TS RPC gets its own
+ * op_id so two concurrent DB ops from the same handler —
+ * `Promise.all([ctx.db.get(a), ctx.db.get(b)])` — don't collide on the
+ * outer call_id. Scheduler/runFn replies still route by call_id (one
+ * outstanding per call is correct for those).
+ */
+const pendingRpcs = new Map<
+  string,
+  {
+    resolve: (data: unknown) => void;
+    reject: (err: Error) => void;
+    timeout: ReturnType<typeof setTimeout>;
+  }
+>();
+
+let opSeq = 0;
+function nextOpId(callId: string): string {
+  opSeq += 1;
+  return `${callId}#${opSeq}`;
+}
+
+/**
+ * Upper bound on how long an individual host → TS RPC (e.g. `ctx.db.get`)
+ * can wait for a reply. The Rust side enforces its own per-handler timeout
+ * (PYLON_FN_CALL_TIMEOUT, default 30s), but if a protocol frame gets
+ * truncated or dropped, the awaiting promise would hang forever. This is
+ * the safety net.
+ *
+ * 60s is deliberately longer than the Rust-side call timeout so that the
+ * host always gets to time out first (with a meaningful error), not the
+ * TS side (with a generic orphaned-rpc error).
+ */
+const RPC_TIMEOUT_MS = 60_000;
+
+async function readerLoop(): Promise<void> {
+  const reader = Bun.stdin.stream().getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    buffer += decoder.decode(value, { stream: true });
+    const lines = buffer.split("\n");
+    buffer = lines.pop() || "";
+
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      dispatch(line);
+    }
+  }
+
+  if (buffer.trim()) dispatch(buffer);
+
+  // stdin closed — the host is gone. Reject every pending RPC so awaiting
+  // handlers unwind instead of hanging and keeping the Bun process alive
+  // forever. Clearing timers avoids keeping the event loop ticking either.
+  for (const [callId, pending] of pendingRpcs) {
+    clearTimeout(pending.timeout);
+    pending.reject(
+      new Error(`host disconnected before reply (call_id=${callId})`),
+    );
+  }
+  pendingRpcs.clear();
+}
+
+function dispatch(line: string): void {
+  let msg: { type: string } & Record<string, unknown>;
+  try {
+    msg = JSON.parse(line);
+  } catch {
+    return;
+  }
+
+  if (msg.type === "call") {
+    // Launch handler; errors are reported back via the protocol, not thrown.
+    handleCall(msg as unknown as CallMessage).catch((err) => {
+      send({
+        type: "error",
+        call_id: (msg as unknown as CallMessage).call_id,
+        code: "HANDLER_CRASH",
+        message: err?.message || String(err),
+      });
+    });
+  } else if (msg.type === "result") {
+    const res = msg as unknown as ResultMessage & { op_id?: string };
+    // Prefer op_id when the host sent it. Fall back to call_id for replies
+    // that don't have one (scheduler / runFn) and for legacy hosts.
+    const key = res.op_id ?? res.call_id;
+    const pending = pendingRpcs.get(key);
+    if (!pending) return;
+    pendingRpcs.delete(key);
+    clearTimeout(pending.timeout);
+    if (res.error) {
+      const err = new Error(res.error.message);
+      (err as any).code = res.error.code;
+      pending.reject(err);
+    } else {
+      pending.resolve(res.data);
+    }
+  }
+}
+
+/**
+ * RPC for DB operations: mints a per-op id so two concurrent DB ops from
+ * the same handler can be in flight at once without colliding. The host
+ * echoes `op_id` back in the `result` reply, which the dispatcher uses
+ * to route the resolution.
+ */
+function rpcDb(
+  callId: string,
+  msg: Record<string, unknown>,
+): Promise<unknown> {
+  const opId = nextOpId(callId);
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      if (pendingRpcs.has(opId)) {
+        pendingRpcs.delete(opId);
+        reject(
+          new Error(
+            `RPC timed out after ${RPC_TIMEOUT_MS}ms (call_id=${callId} op_id=${opId})`,
+          ),
+        );
+      }
+    }, RPC_TIMEOUT_MS);
+    pendingRpcs.set(opId, { resolve, reject, timeout });
+    send({ ...msg, call_id: callId, op_id: opId });
+  });
+}
+
+/**
+ * RPC for non-db protocol replies (scheduler.runAfter, nested function
+ * calls, etc.) where at-most-one in-flight per call_id is the right
+ * contract. Keeps the legacy keying so these reply shapes don't need
+ * op_id support on the host.
+ */
+function rpc(callId: string, msg: Record<string, unknown>): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    if (pendingRpcs.has(callId)) {
+      reject(
+        new Error(
+          `Internal: concurrent RPC attempted on same call_id (${callId})`,
+        ),
+      );
+      return;
+    }
+    const timeout = setTimeout(() => {
+      if (pendingRpcs.has(callId)) {
+        pendingRpcs.delete(callId);
+        reject(
+          new Error(
+            `RPC timed out after ${RPC_TIMEOUT_MS}ms (call_id=${callId})`,
+          ),
+        );
+      }
+    }, RPC_TIMEOUT_MS);
+    pendingRpcs.set(callId, { resolve, reject, timeout });
+    send({ ...msg, call_id: callId });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Context builders
+// ---------------------------------------------------------------------------
+
+function buildDbReader(callId: string): DbReader {
+  // All DB ops use rpcDb so Promise.all over ctx.db reads can run in
+  // parallel without colliding on the outer call_id key.
+  return {
+    async get(entity, id) {
+      return (await rpcDb(callId, { type: "db", op: "get", entity, id })) as any;
+    },
+    async list(entity) {
+      return (await rpcDb(callId, { type: "db", op: "list", entity })) as any;
+    },
+    async lookup(entity, field, value) {
+      return (await rpcDb(callId, {
+        type: "db",
+        op: "lookup",
+        entity,
+        field,
+        value,
+      })) as any;
+    },
+    async query(entity, filter) {
+      return (await rpcDb(callId, {
+        type: "db",
+        op: "query",
+        entity,
+        data: filter,
+      })) as any;
+    },
+    async queryGraph(query) {
+      return (await rpcDb(callId, {
+        type: "db",
+        op: "query_graph",
+        entity: "",
+        data: query,
+      })) as any;
+    },
+    async paginate(entity, opts) {
+      // Clamp on the client side too so a caller never wastes a round trip
+      // with out-of-range values. The Rust side re-clamps.
+      const numItems = Math.max(1, Math.min(1000, opts.numItems | 0));
+      return (await rpcDb(callId, {
+        type: "db",
+        op: "paginate",
+        entity,
+        after: opts.cursor ?? undefined,
+        limit: numItems,
+      })) as any;
+    },
+  };
+}
+
+function buildDbWriter(callId: string): DbWriter {
+  const reader = buildDbReader(callId);
+  return {
+    ...reader,
+    async insert(entity, data) {
+      const r = (await rpcDb(callId, {
+        type: "db",
+        op: "insert",
+        entity,
+        data,
+      })) as { id: string };
+      return r.id;
+    },
+    async update(entity, id, data) {
+      const r = (await rpcDb(callId, {
+        type: "db",
+        op: "update",
+        entity,
+        id,
+        data,
+      })) as { updated: boolean };
+      return r.updated;
+    },
+    async delete(entity, id) {
+      const r = (await rpcDb(callId, {
+        type: "db",
+        op: "delete",
+        entity,
+        id,
+      })) as { deleted: boolean };
+      return r.deleted;
+    },
+    async link(entity, id, relation, targetId) {
+      const r = (await rpcDb(callId, {
+        type: "db",
+        op: "link",
+        entity,
+        id,
+        relation,
+        target_id: targetId,
+      })) as { linked: boolean };
+      return r.linked;
+    },
+    async unlink(entity, id, relation) {
+      const r = (await rpcDb(callId, {
+        type: "db",
+        op: "unlink",
+        entity,
+        id,
+        relation,
+      })) as { unlinked: boolean };
+      return r.unlinked;
+    },
+  };
+}
+
+function buildStream(callId: string): Stream {
+  return {
+    write(data: string) {
+      // Stream messages are fire-and-forget; they don't get a `result` reply.
+      send({ type: "stream", call_id: callId, data });
+    },
+    writeEvent(event: string, data: string) {
+      send({ type: "stream", call_id: callId, data, event });
+    },
+  };
+}
+
+function buildScheduler(callId: string): Scheduler {
+  return {
+    async runAfter(delayMs, fnName, args) {
+      const r = (await rpc(callId, {
+        type: "schedule",
+        fn_name: fnName,
+        args,
+        delay_ms: delayMs,
+      })) as { id?: string };
+      return r.id || "";
+    },
+    async runAt(timestamp, fnName, args) {
+      const r = (await rpc(callId, {
+        type: "schedule",
+        fn_name: fnName,
+        args,
+        run_at: timestamp,
+      })) as { id?: string };
+      return r.id || "";
+    },
+    async cancel(scheduleId) {
+      await rpc(callId, {
+        type: "cancel_schedule",
+        schedule_id: scheduleId,
+      });
+    },
+  };
+}
+
+function buildActionCtx(
+  callId: string,
+  auth: AuthInfo,
+  stream: Stream,
+  scheduler: Scheduler,
+  request?: unknown
+): ActionCtx {
+  // The host sends `request` as snake_case JSON (`raw_body`); normalize it
+  // to the camelCase shape documented in ActionCtx so action authors don't
+  // have to care about the transport. Absent when invoked programmatically.
+  let normalizedRequest: ActionCtx["request"];
+  if (request && typeof request === "object") {
+    const r = request as Record<string, unknown>;
+    normalizedRequest = {
+      method: String(r.method ?? ""),
+      path: String(r.path ?? ""),
+      headers: (r.headers as Record<string, string>) ?? {},
+      rawBody: String(r.raw_body ?? r.rawBody ?? ""),
+    };
+  }
+  return {
+    auth,
+    stream,
+    scheduler,
+    env: process.env as Record<string, string>,
+    async runQuery(fnName, args) {
+      return rpc(callId, {
+        type: "run_fn",
+        fn_name: fnName,
+        fn_type: "query",
+        args,
+      }) as Promise<any>;
+    },
+    async runMutation(fnName, args) {
+      return rpc(callId, {
+        type: "run_fn",
+        fn_name: fnName,
+        fn_type: "mutation",
+        args,
+      }) as Promise<any>;
+    },
+    error(code, message) {
+      const err = new Error(message);
+      (err as any).code = code;
+      return err;
+    },
+    request: normalizedRequest,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+const registry = new Map<string, FnDefinition>();
+
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+
+async function handleCall(msg: CallMessage): Promise<void> {
+  const def = registry.get(msg.fn_name);
+
+  if (!def) {
+    send({
+      type: "error",
+      call_id: msg.call_id,
+      code: "FN_NOT_FOUND",
+      message: `Function "${msg.fn_name}" not registered`,
+    });
+    return;
+  }
+
+  // Enforce that the caller's declared fn_type matches what's registered.
+  // Without this, a buggy or malicious peer could label a mutation call as
+  // a query and break host-side assumptions about side effects / auth.
+  // Accept msg.fn_type undefined for backwards compatibility — the host
+  // always sends it in current versions.
+  if (msg.fn_type && msg.fn_type !== def.type) {
+    send({
+      type: "error",
+      call_id: msg.call_id,
+      code: "FN_TYPE_MISMATCH",
+      message: `Function "${msg.fn_name}" is registered as ${def.type}, not ${msg.fn_type}`,
+    });
+    return;
+  }
+
+  if (def.args) {
+    const { valid, errors } = validateArgs(msg.args, def.args);
+    if (!valid) {
+      send({
+        type: "error",
+        call_id: msg.call_id,
+        code: "INVALID_ARGS",
+        message: errors.join("; "),
+      });
+      return;
+    }
+  }
+
+  const stream = buildStream(msg.call_id);
+  const scheduler = buildScheduler(msg.call_id);
+
+  // Normalize the Rust-side auth envelope (snake_case) to the camelCase
+  // shape that AuthInfo documents. Handlers read `ctx.auth.userId`; the
+  // wire uses `user_id`. Without this adapter every handler's
+  // `if (!ctx.auth.userId)` check fires and authenticated calls come
+  // back as UNAUTHENTICATED. Accept both shapes so old TS runtimes that
+  // already got camelCase don't regress.
+  const rawAuth = msg.auth as unknown as Record<string, unknown>;
+  const auth: AuthInfo = {
+    userId: ((rawAuth.userId ?? rawAuth.user_id) as string | null | undefined) ?? null,
+    isAdmin: Boolean(rawAuth.isAdmin ?? rawAuth.is_admin),
+    tenantId:
+      ((rawAuth.tenantId ?? rawAuth.tenant_id) as string | null | undefined) ??
+      null,
+  };
+
+  let ctx: QueryCtx | MutationCtx | ActionCtx;
+  switch (def.type) {
+    case "query":
+      ctx = { db: buildDbReader(msg.call_id), auth };
+      break;
+    case "mutation":
+      ctx = {
+        db: buildDbWriter(msg.call_id),
+        auth,
+        stream,
+        scheduler,
+        error(code, message) {
+          const err = new Error(message);
+          (err as any).code = code;
+          return err;
+        },
+      };
+      break;
+    case "action":
+      // Pass `msg.request` so actions invoked via `defineRoute` HTTP
+      // bindings can reach raw headers + body (for webhook signature
+      // verification). Programmatic invocations (runAction, jobs) get
+      // undefined here and `ctx.request` reads as undefined — the type
+      // is optional on purpose.
+      ctx = buildActionCtx(
+        msg.call_id,
+        auth,
+        stream,
+        scheduler,
+        (msg as unknown as { request?: unknown }).request,
+      );
+      break;
+  }
+
+  try {
+    const result = await def.handler(ctx, msg.args);
+    send({
+      type: "return",
+      call_id: msg.call_id,
+      value: result ?? null,
+    });
+  } catch (err: any) {
+    // Redact. Handler errors historically shipped raw `err.message` to the
+    // caller, which leaked DB error text, stack-trace-looking strings, and
+    // internal concurrency-invariant messages. Authors can still surface a
+    // caller-safe message by throwing with an explicit `code` AND a message
+    // they're willing to disclose: `ctx.error(code, message)` uses that
+    // pattern. Anything else gets a generic message; the full error is
+    // logged to stderr where the operator can see it.
+    const hasExplicitCode = typeof err?.code === "string" && err.code.length > 0;
+    if (hasExplicitCode) {
+      send({
+        type: "error",
+        call_id: msg.call_id,
+        code: err.code,
+        message:
+          typeof err.message === "string" && err.message.length > 0
+            ? err.message
+            : "Handler error",
+      });
+    } else {
+      // No explicit code — assume it's an unexpected Error/thrown value.
+      // Log the real error to stderr (server operator visible) and return
+      // a safe placeholder to the client.
+      console.error(
+        `[functions] unhandled error in ${msg.fn_name} (${msg.call_id}):`,
+        err,
+      );
+      send({
+        type: "error",
+        call_id: msg.call_id,
+        code: "HANDLER_ERROR",
+        message: "Internal handler error",
+      });
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Startup: scan functions dir, send ready, then start reader loop
+// ---------------------------------------------------------------------------
+
+async function main() {
+  // Fence user `console.*` away from stdout BEFORE any user code is
+  // imported — the import side-effects alone could print a stray line
+  // that the host parses as a protocol frame.
+  fenceStdout();
+
+  const fnDir = process.argv[2] || "./functions";
+
+  let files: string[];
+  try {
+    files = readdirSync(fnDir).filter(
+      (f) => f.endsWith(".ts") || f.endsWith(".js")
+    );
+  } catch {
+    send({
+      type: "ready",
+      functions: [],
+      error: `Cannot read functions directory: ${fnDir}`,
+    });
+    return;
+  }
+
+  for (const file of files) {
+    const name = basename(file, file.endsWith(".ts") ? ".ts" : ".js");
+    try {
+      const mod = await import(join(process.cwd(), fnDir, file));
+      const def = mod.default as FnDefinition;
+      if (def && def.type && def.handler) {
+        registry.set(name, def);
+      }
+    } catch (err) {
+      console.error(`[functions] Failed to load ${file}:`, err);
+    }
+  }
+
+  const functions = Array.from(registry.entries()).map(([name, def]) => ({
+    name,
+    fn_type: def.type,
+    args_schema: def.args || null,
+  }));
+  send({ type: "ready", functions });
+
+  await readerLoop();
+}
+
+main().catch((err) => {
+  console.error("[functions] Fatal error:", err);
+  process.exit(1);
+});

package/src/testing.ts

@@ -0,0 +1,70 @@
+/**
+ * Test-side helpers for `pylon test`.
+ *
+ * The CLI already starts each test FILE with a fresh in-memory database
+ * (`PYLON_IN_MEMORY=1`), so tests across files never cross-contaminate.
+ * This module covers the finer-grained case: isolating individual
+ * `test(...)` blocks within a single file.
+ *
+ * Two integration patterns are supported:
+ *
+ * 1. **Manual** — call `resetDb()` from a `beforeEach` hook.
+ * 2. **Automatic** — call `installTestIsolation()` at the top of the file
+ *    and every `test()` block runs with a reset store.
+ *
+ * Both require the test file to run under `pylon test` (not raw
+ * `bun test`), because resetDb talks to the server via HTTP.
+ */
+
+const DEFAULT_BASE_URL = "http://localhost:4321";
+
+/**
+ * Reset the in-memory database to empty. Returns when the server confirms.
+ *
+ * Only works when the server is running in in-memory dev mode — production
+ * deployments refuse this call. Safe to no-op when the reset endpoint is
+ * unreachable so tests using this helper still work under raw `bun test`
+ * (they just won't reset between cases).
+ */
+export async function resetDb(
+  baseUrl: string = DEFAULT_BASE_URL,
+): Promise<void> {
+  try {
+    const res = await fetch(`${baseUrl}/api/__test__/reset`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+    });
+    if (!res.ok && res.status !== 404) {
+      const body = await res.text().catch(() => "");
+      throw new Error(
+        `resetDb failed: ${res.status} ${body.slice(0, 200)}`,
+      );
+    }
+  } catch (err: any) {
+    // Fetch may throw if the server isn't up yet. Tests that don't need
+    // isolation still succeed; tests that do will see pollution and fail
+    // loudly on their own assertions. Log so authors can debug.
+    // eslint-disable-next-line no-console
+    console.warn("[pylon-test] resetDb skipped:", err?.message ?? err);
+  }
+}
+
+/**
+ * Bun-friendly `beforeEach(resetDb)` installer. Looks up Bun's global
+ * `beforeEach` via `globalThis`; no-ops under other runners.
+ */
+export function installTestIsolation(
+  baseUrl: string = DEFAULT_BASE_URL,
+): void {
+  const g = globalThis as any;
+  if (typeof g.beforeEach === "function") {
+    g.beforeEach(() => resetDb(baseUrl));
+  } else {
+    // eslint-disable-next-line no-console
+    console.warn(
+      "[pylon-test] installTestIsolation: no global beforeEach found — run via `pylon test` or `bun test`",
+    );
+  }
+}

package/src/types.ts

@@ -0,0 +1,236 @@
+/**
+ * Type definitions for the function system.
+ */
+
+// ---------------------------------------------------------------------------
+// Auth
+// ---------------------------------------------------------------------------
+
+export interface AuthInfo {
+  userId: string | null;
+  isAdmin: boolean;
+  /** Active tenant id (selected organization) for multi-tenant apps.
+   *  Null when the session hasn't selected one. */
+  tenantId: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Database — read operations
+// ---------------------------------------------------------------------------
+
+export interface DbReader {
+  /** Get a single row by ID. Returns null if not found. */
+  get(entity: string, id: string): Promise<Record<string, unknown> | null>;
+
+  /** List all rows for an entity. */
+  list(entity: string): Promise<Record<string, unknown>[]>;
+
+  /** Lookup a row by a field value (e.g., email). */
+  lookup(
+    entity: string,
+    field: string,
+    value: string
+  ): Promise<Record<string, unknown> | null>;
+
+  /** Query with filters ($gt, $lt, $in, $like, $order, $limit, etc.). */
+  query(
+    entity: string,
+    filter: Record<string, unknown>
+  ): Promise<Record<string, unknown>[]>;
+
+  /** Execute a graph query with nested relation includes. */
+  queryGraph(
+    query: Record<string, unknown>
+  ): Promise<Record<string, unknown>>;
+
+  /**
+   * Cursor-paginated list. Pass `cursor` from a previous page's `nextCursor`
+   * to continue; pass `null` for the first page.
+   *
+   * ```ts
+   * const { page, nextCursor, isDone } =
+   *   await ctx.db.paginate("Order", { cursor: null, numItems: 50 });
+   * ```
+   *
+   * `numItems` is clamped to [1, 1000]; the server honors the clamp.
+   */
+  paginate(
+    entity: string,
+    opts: { cursor: string | null; numItems: number }
+  ): Promise<PaginationResult>;
+}
+
+/** Result shape for [`DbReader.paginate`]. */
+export interface PaginationResult<T = Record<string, unknown>> {
+  /** Rows in this page. */
+  page: T[];
+  /** Cursor to pass to the next `paginate` call. `null` when exhausted. */
+  nextCursor: string | null;
+  /** True when there are no more rows after this page. */
+  isDone: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Database — write operations (extends read)
+// ---------------------------------------------------------------------------
+
+export interface DbWriter extends DbReader {
+  /** Insert a new row. Returns the generated ID. */
+  insert(entity: string, data: Record<string, unknown>): Promise<string>;
+
+  /** Update a row by ID. Returns true if the row existed. */
+  update(
+    entity: string,
+    id: string,
+    data: Record<string, unknown>
+  ): Promise<boolean>;
+
+  /** Delete a row by ID. Returns true if the row existed. */
+  delete(entity: string, id: string): Promise<boolean>;
+
+  /** Link two entities via a relation. */
+  link(
+    entity: string,
+    id: string,
+    relation: string,
+    targetId: string
+  ): Promise<boolean>;
+
+  /** Unlink a relation (set FK to null). */
+  unlink(entity: string, id: string, relation: string): Promise<boolean>;
+}
+
+// ---------------------------------------------------------------------------
+// Streaming
+// ---------------------------------------------------------------------------
+
+export interface Stream {
+  /** Write a text chunk to the client (SSE). */
+  write(data: string): void;
+
+  /** Write a typed SSE event. */
+  writeEvent(event: string, data: string): void;
+}
+
+// ---------------------------------------------------------------------------
+// Scheduler
+// ---------------------------------------------------------------------------
+
+export interface Scheduler {
+  /** Schedule a function to run after a delay (milliseconds). */
+  runAfter(
+    delayMs: number,
+    fnName: string,
+    args: Record<string, unknown>
+  ): Promise<string>;
+
+  /** Schedule a function to run at a specific time (Unix ms). */
+  runAt(
+    timestamp: number,
+    fnName: string,
+    args: Record<string, unknown>
+  ): Promise<string>;
+
+  /** Cancel a previously scheduled function. */
+  cancel(scheduleId: string): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Context objects — what handlers receive
+// ---------------------------------------------------------------------------
+
+/** Context for query handlers (read-only). */
+export interface QueryCtx {
+  db: DbReader;
+  auth: AuthInfo;
+}
+
+/** Context for mutation handlers (read + write, transactional). */
+export interface MutationCtx {
+  db: DbWriter;
+  auth: AuthInfo;
+  stream: Stream;
+  scheduler: Scheduler;
+  /** Create a typed error that triggers rollback. */
+  error(code: string, message: string): Error;
+}
+
+/** Context for action handlers (external I/O, non-transactional). */
+export interface ActionCtx {
+  auth: AuthInfo;
+  stream: Stream;
+  scheduler: Scheduler;
+  /** Environment variables / secrets. */
+  env: Record<string, string>;
+  /** Run a registered query within its own read transaction. */
+  runQuery<T = unknown>(
+    fnName: string,
+    args: Record<string, unknown>
+  ): Promise<T>;
+  /** Run a registered mutation within its own write transaction. */
+  runMutation<T = unknown>(
+    fnName: string,
+    args: Record<string, unknown>
+  ): Promise<T>;
+  /** Create a typed error. */
+  error(code: string, message: string): Error;
+  /**
+   * HTTP request metadata — present only when the action was invoked via
+   * a `defineRoute` HTTP binding. Missing when the action is called from
+   * another action (`ctx.runAction`), a job, or the function dashboard.
+   *
+   * Use this to verify webhook signatures (Stripe, GitHub, Slack) that
+   * require the raw request body — `rawBody` is the exact bytes the
+   * signer signed, NOT the parsed JSON.
+   *
+   * ```ts
+   * export default action({
+   *   async handler(ctx) {
+   *     const sig = ctx.request?.headers["stripe-signature"];
+   *     stripe.webhooks.constructEvent(ctx.request!.rawBody, sig!, secret);
+   *   },
+   * });
+   * ```
+   */
+  request?: RequestInfo;
+}
+
+/** HTTP request metadata available on an action's ctx when invoked via an
+ *  HTTP route binding. Header names are lowercased. */
+export interface RequestInfo {
+  method: string;
+  path: string;
+  headers: Record<string, string>;
+  rawBody: string;
+}
+
+// ---------------------------------------------------------------------------
+// Function definition types
+// ---------------------------------------------------------------------------
+
+export type FnType = "query" | "mutation" | "action";
+
+export interface FnDefinition<TArgs = unknown, TReturn = unknown> {
+  type: FnType;
+  args?: Record<string, Validator>;
+  handler: (ctx: any, args: TArgs) => Promise<TReturn>;
+}
+
+// ---------------------------------------------------------------------------
+// Validators
+// ---------------------------------------------------------------------------
+
+export interface Validator {
+  type: string;
+  optional?: boolean;
+  /** For v.id("tableName") */
+  table?: string;
+  /** For v.array(v.string()) */
+  items?: Validator;
+  /** For v.object({...}) */
+  fields?: Record<string, Validator>;
+  /** For v.union(...) */
+  variants?: Validator[];
+  /** For v.literal("value") */
+  value?: unknown;
+}

package/src/validators.ts

@@ -0,0 +1,199 @@
+/**
+ * Argument validators for function definitions.
+ *
+ * These serve double duty:
+ * 1. Runtime validation — reject bad input before the handler runs.
+ * 2. Type inference — TypeScript infers handler arg types from validators.
+ *
+ * @example
+ * ```typescript
+ * import { mutation, v } from "@pylonsync/functions";
+ *
+ * export default mutation({
+ *   args: {
+ *     name: v.string(),
+ *     age: v.optional(v.number()),
+ *     tags: v.array(v.string()),
+ *   },
+ *   async handler(ctx, args) {
+ *     // args is typed as { name: string, age?: number, tags: string[] }
+ *   },
+ * });
+ * ```
+ */
+
+import type { Validator } from "./types";
+
+function validator(type: string, extra?: Partial<Validator>): Validator {
+  return { type, ...extra };
+}
+
+export const v = {
+  /** String value. */
+  string: (): Validator => validator("string"),
+
+  /** Number (float64). Same as `v.float()`. */
+  number: (): Validator => validator("number"),
+
+  /**
+   * 64-bit float. Alias for `v.number()` so the validator API matches the
+   * schema DSL (which uses `field.float()`). Prefer this in new code.
+   */
+  float: (): Validator => validator("number"),
+
+  /** Integer. */
+  int: (): Validator => validator("int"),
+
+  /** Boolean. Same as `v.bool()`. */
+  boolean: (): Validator => validator("boolean"),
+
+  /**
+   * Boolean. Alias for `v.boolean()` so the validator API matches the
+   * schema DSL (which uses `field.bool()`). Prefer this in new code.
+   */
+  bool: (): Validator => validator("boolean"),
+
+  /**
+   * ISO-8601 datetime string. Validates the shape of a string value; the
+   * stored column type comes from the schema (`field.datetime()`).
+   */
+  datetime: (): Validator => validator("string"),
+
+  /**
+   * Richtext string. Same runtime validation as `v.string()`; named
+   * explicitly so server functions read as the matching schema type.
+   */
+  richtext: (): Validator => validator("string"),
+
+  /** ID reference to another entity. */
+  id: (table: string): Validator => validator("id", { table }),
+
+  /** Null value. */
+  null: (): Validator => validator("null"),
+
+  /** Array of values. */
+  array: (items: Validator): Validator => validator("array", { items }),
+
+  /** Object with typed fields. */
+  object: (fields: Record<string, Validator>): Validator =>
+    validator("object", { fields }),
+
+  /** Optional value (may be omitted). */
+  optional: (inner: Validator): Validator => ({ ...inner, optional: true }),
+
+  /** Union of multiple types. */
+  union: (...variants: Validator[]): Validator =>
+    validator("union", { variants }),
+
+  /** Exact literal value. */
+  literal: (value: string | number | boolean): Validator =>
+    validator("literal", { value }),
+
+  /** Any valid JSON value. */
+  any: (): Validator => validator("any"),
+};
+
+// ---------------------------------------------------------------------------
+// Runtime validation
+// ---------------------------------------------------------------------------
+
+export function validateArgs(
+  args: unknown,
+  schema: Record<string, Validator>
+): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  if (typeof args !== "object" || args === null) {
+    return { valid: false, errors: ["args must be an object"] };
+  }
+
+  const obj = args as Record<string, unknown>;
+
+  for (const [key, validator] of Object.entries(schema)) {
+    const value = obj[key];
+
+    if (value === undefined || value === null) {
+      if (!validator.optional) {
+        errors.push(`Missing required field "${key}" (type: ${validator.type})`);
+      }
+      continue;
+    }
+
+    const err = validateValue(value, validator, key);
+    if (err) errors.push(err);
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+function validateValue(
+  value: unknown,
+  validator: Validator,
+  path: string
+): string | null {
+  switch (validator.type) {
+    case "string":
+      return typeof value === "string"
+        ? null
+        : `${path}: expected string, got ${typeof value}`;
+    case "number":
+    case "int":
+      return typeof value === "number"
+        ? null
+        : `${path}: expected number, got ${typeof value}`;
+    case "boolean":
+      return typeof value === "boolean"
+        ? null
+        : `${path}: expected boolean, got ${typeof value}`;
+    case "id":
+      return typeof value === "string"
+        ? null
+        : `${path}: expected id string, got ${typeof value}`;
+    case "null":
+      return value === null
+        ? null
+        : `${path}: expected null, got ${typeof value}`;
+    case "any":
+      return null;
+    case "literal":
+      return value === validator.value
+        ? null
+        : `${path}: expected literal ${JSON.stringify(validator.value)}, got ${JSON.stringify(value)}`;
+    case "array":
+      if (!Array.isArray(value))
+        return `${path}: expected array, got ${typeof value}`;
+      if (validator.items) {
+        for (let i = 0; i < value.length; i++) {
+          const err = validateValue(value[i], validator.items, `${path}[${i}]`);
+          if (err) return err;
+        }
+      }
+      return null;
+    case "object":
+      if (typeof value !== "object" || value === null || Array.isArray(value))
+        return `${path}: expected object`;
+      if (validator.fields) {
+        for (const [k, v] of Object.entries(validator.fields)) {
+          const fieldVal = (value as Record<string, unknown>)[k];
+          if (fieldVal === undefined && !v.optional) {
+            return `${path}.${k}: required field missing`;
+          }
+          if (fieldVal !== undefined) {
+            const err = validateValue(fieldVal, v, `${path}.${k}`);
+            if (err) return err;
+          }
+        }
+      }
+      return null;
+    case "union":
+      if (validator.variants) {
+        for (const variant of validator.variants) {
+          if (validateValue(value, variant, path) === null) return null;
+        }
+        return `${path}: value does not match any variant`;
+      }
+      return null;
+    default:
+      return null;
+  }
+}