# Capsule Spec ``` capsule-spec: 1 ``` **Capsule Spec v1.** This is the authoritative, versioned definition of the Pond capsule application format and its wire protocol. A program **conforms to Capsule Spec v1** if (a) its source tree matches the directory contract and hard constraints below, and (b) it only depends on the server API, client API, and HTTP wire protocol defined here. Any runtime that mounts the routes in [§5 Wire Protocol](#5-wire-protocol) with the request/response shapes given is a **conformant runtime**: a Spec v1 capsule will run on it unchanged. This spec is derived directly from the runtime source (`src/server/index.ts`, `client/index.ts`, `src/runtime.ts`). Where prior prose docs disagreed with the code, the code wins; the disagreements are listed in [§8 Conformance notes & known doc drift](#8-conformance-notes--known-doc-drift). Keywords **MUST**, **MUST NOT**, **SHOULD**, **MAY** are used in the RFC 2119 sense. --- ## 1. Directory contract A capsule is a directory with this layout: ```text / server/index.ts # REQUIRED — exports default capsule({...}) client/index.tsx # REQUIRED — exports a Preact component named App shared/ # OPTIONAL — pure TypeScript shared by both sides package.json # REQUIRED — must not declare npm lifecycle scripts (see §1.4) .env.pond.server # OPTIONAL — KEY=VALUE secrets, never bundled to the client ``` ### 1.1 `server/index.ts` - **MUST** end with a default export of `capsule({...})`: `export default capsule({ schema, queries, mutations, ... })`. - **MUST** import its primitives only from `pond/server`. - **MAY** import plain relative TypeScript (e.g. `../shared/...`) and Node built-ins that ship with the runtime. - **MUST NOT** import arbitrary npm packages. The server file is bundled with esbuild using `packages: "external"` against an alias that resolves `pond/server` to the runtime; nothing else is provided. ### 1.2 `client/index.tsx` - **MUST** export a Preact component named `App`. The runtime's HTML shell mounts `` automatically; manual `render()` is not required. - **MUST** import its hooks/components only from `pond/client`. - **MAY** import plain relative TypeScript (e.g. `../shared/...`). - **MUST NOT** import React, react-router, react-query, or any other npm UI library. Preact is the renderer; Tailwind utility classes are available without configuration (the runtime injects Tailwind). ### 1.3 `shared/` purity - Files under `shared/` **MUST** be pure TypeScript importable by both server and client. - They **MUST NOT** read env or secrets, touch DOM APIs, touch Node APIs, or call any pond runtime API (`pond/server` / `pond/client`). Keep them to types and pure functions. ### 1.4 `package.json` - **MUST** exist. **MUST NOT** be deleted. - **MUST NOT** declare npm lifecycle scripts (`preinstall`, `install`, `postinstall`, `prepare`, `postprepare`). Conformant control planes reject uploads containing them, and `pond fork` refuses to fork them without `--allow-scripts`. They are an RCE vector. ### 1.5 Authorization is the handler's job The runtime resolves an identity into `ctx.auth` (see §3.4) but does **not** enforce any access control on queries, mutations, or endpoints. Every handler is responsible for its own authorization: - Filter reads by `ctx.auth.userId`. - Re-check ownership on every `update` / `delete`. - Treat `ctx.auth.isGuest === true` as "no signed-in user". There is no per-row ACL and no automatic owner column. If you do not check, the data is effectively public to anyone who can reach the route. --- ## 2. Required imports ```ts // server/index.ts import { capsule, query, mutation, endpoint, socket, table, string, number, boolean, json, text } from "pond/server" // client/index.tsx import { useQuery, useMutation, useAuth, SignInWithGoogle, signOut, render, h } from "pond/client" ``` A capsule **MUST NOT** import any symbol from `pond/server` or `pond/client` that is not listed in §3 / §4. --- ## 3. Server API contract (`pond/server`) All signatures below are taken verbatim from `src/server/index.ts`. ### 3.1 Column types ```ts interface ColumnType { _sqlType: string } string(): ColumnType // SQL TEXT number(): ColumnType // SQL REAL (integers and floats both round-trip) boolean(): ColumnType // SQL INTEGER (JS true/false coerced to 1/0 on write, // read back as numeric 1/0) ``` `ColumnType` is opaque — the only field is `_sqlType`, used by the runtime to emit `CREATE TABLE`. Capsules **MUST NOT** construct `ColumnType` by hand; use the three helpers. ### 3.2 `table` ```ts table>(columns: T): T ``` Identity marker function. The object passed in is the table's user-defined columns. The runtime adds three columns to **every** table automatically: | Column | SQL | | ----------- | --------------------------------------------------------------- | | `id` | `TEXT PRIMARY KEY` (UUID, set on insert) | | `createdAt` | `TEXT DEFAULT (datetime('now'))` | | `updatedAt` | `TEXT DEFAULT (datetime('now'))` (re-stamped on every `update`) | **Identifier rules** (enforced at migration time and on every dynamic column reference in `ctx.db`). A table or column name **MUST**: - match `/^[A-Za-z_][A-Za-z0-9_]*$/`, - be at most 64 characters, - not start with the reserved `_pond_` prefix, - not be a SQLite reserved word (e.g. `order`, `group`, `where`, `select`, …). Violations throw `Invalid identifier`, `Identifier too long`, the `_pond_` reserved-prefix error, or `Identifier "X" is a SQLite reserved word`. ### 3.3 `capsule` ```ts capsule(def: { schema: Record> // REQUIRED queries: Record // REQUIRED mutations: Record // REQUIRED endpoints?: Record sockets?: Record allowedOrigins?: string[] rateLimit?: Record public?: boolean static?: boolean title?: string description?: string }): CapsuleDefinition ``` - `schema` keys are table names; each value is the column map from `table(...)`. - `queries` / `mutations` map a route name to a handler (see §3.5). - `endpoints` map a name to either an `endpoint(...)` definition (preferred) or a bare handler function. A bare function has no method/path and defaults to `GET /api/` (see §5.4). - `sockets` map a name to a `socket(...)` handler. Sockets are part of the format but are **not** carried over the hosted control-plane proxy in v1 (the local dev/`pond start` runtime mounts them; see §8). - `rateLimit` keys match query / mutation / endpoint **names** (see §3.7). - `public`, `title`, `description` feed the public listing / fork surface. - `static: true` deploys the capsule as a pure static site — the host serves the prebuilt `client.html` directly and never boots a worker, so there is no server runtime (no DB/auth/AI/blobs; `/api/*` returns 404). Requires a `client/index.tsx`; `schema`/`queries`/`mutations` may be empty. `schema`, `queries`, and `mutations` are required object literals. Empty objects are allowed (`queries: {}`). ### 3.4 Context (`ctx`) Every query, mutation, endpoint, and socket handler receives the same context as its first argument: ```ts interface CapsuleContext { auth: CapsuleAuth db: CapsuleDb env: Record log: CapsuleLog ai: CapsuleAi blob: CapsuleBlob } ``` > Note: older prose docs listed only `auth/db/env/log`. The actual context object > built by the runtime (`buildContext`) always includes `ai` and `blob` too. #### 3.4.1 `ctx.auth` — `CapsuleAuth` ```ts interface CapsuleAuth { isGuest: boolean userId: string // "guest" for unauthenticated callers displayName?: string picture?: string email?: string } ``` Resolved per request from the `pond_session` JWT cookie. No cookie / invalid / expired ⇒ guest (`{ isGuest: true, userId: "guest", displayName: "Guest" }`). Provider user-id shapes: Google ⇒ ``, GitHub ⇒ `github:`, email magic link ⇒ `email:`. #### 3.4.2 `ctx.db` — `CapsuleDb` A proxy with one property per schema table. Each table exposes: ```ts interface CapsuleDbTable { where(column: string, value: any): QueryBuilder // chainable; multiple ANDed orderBy(column: string, dir: "asc" | "desc"): QueryBuilder limit(n: number): QueryBuilder all(): any[] // runs SELECT * get(id: string): any // SELECT by id; row or undefined insert(data: Record): any // generates UUID id; returns row update(id: string, data: Record): any // re-stamps updatedAt; returns row delete(id: string): void } interface QueryBuilder { orderBy(column: string, dir: "asc" | "desc"): QueryBuilder limit(n: number): QueryBuilder all(): any[] } ``` Semantics derived from the runtime's `buildDbProxy`: - `where`/`orderBy`/`limit` are immutable builders; chaining returns a new builder. Nothing executes until `.all()`, `.get()`, `.insert()`, etc. - `where(col, val)` adds `col = ?`; multiple `where` calls are joined with `AND`. - `orderBy` `dir` **MUST** be `"asc"` or `"desc"`; anything else throws. - Every `column` / table name passed dynamically is re-validated against the identifier rules in §3.2. - `boolean` values bound through `insert`/`update` are coerced to `1`/`0`. - `insert` returns the freshly inserted row (including generated `id`, `createdAt`, `updatedAt`). #### 3.4.3 `ctx.env` `Record` loaded from `.env.pond.server` (`KEY=VALUE`, `#` comments). `GOOGLE_REDIRECT_URI` is derived from the dev port when not set. #### 3.4.4 `ctx.log` — `CapsuleLog` ```ts interface CapsuleLog { info(msg: string, data?: any): void error(msg: string, data?: any): void } ``` #### 3.4.5 `ctx.ai` — `CapsuleAi` ```ts interface AiCompleteOptions { prompt: string model?: string system?: string maxTokens?: number temperature?: number } interface CapsuleAi { complete(opts: AiCompleteOptions): Promise stream(opts: AiCompleteOptions): AsyncIterable } ``` Provider is chosen from env: explicit `AI_PROVIDER=anthropic|openai|hermes`, else first of `ANTHROPIC_API_KEY` → `OPENAI_API_KEY` → `HERMES_BASE_URL`. With none configured, `complete`/`stream` throw. In v1, `stream` yields a single full string (non-progressive fallback). #### 3.4.6 `ctx.blob` — `CapsuleBlob` ```ts interface CapsuleBlob { put( key: string, bytes: Uint8Array | ArrayBuffer | Buffer | string, options?: { contentType?: string }, ): Promise<{ key: string; size: number }> get(key: string): Promise<{ bytes: Buffer; contentType: string } | null> delete(key: string): Promise list(prefix?: string): Promise> } ``` Keys **MUST** match `/^[A-Za-z0-9._/-]+$/`, **MUST NOT** contain `..`, and **MUST NOT** start with `/`; otherwise `put`/`get` throw. Blobs are readable over the wire at `GET /api/blob/` with **no** built-in access control (§5.5). ### 3.5 Handlers ```ts type QueryHandler = (ctx: CapsuleContext, ...args: TArgs) => TResult | Promise type MutationHandler = (ctx: CapsuleContext, ...args: TArgs) => TResult | Promise query(handler: QueryHandler): QueryHandler mutation(handler: MutationHandler): MutationHandler ``` `query()` / `mutation()` are identity wrappers that mark a function. The return value **MUST** be JSON-serializable; it is sent back via `c.json(result)`. A mutation **MAY** return nothing (`void`) — the response is then an empty body (see §5.2/§5.3 and §4.1 for how the client handles that). ### 3.6 Endpoints ```ts interface EndpointRequest { headers: Headers query: Record json(): Promise text(): Promise bytes(): Promise } interface EndpointResponse { body: string | null status: number headers: Record } type EndpointHandler = (ctx: CapsuleContext, req: EndpointRequest) => EndpointResponse | Promise endpoint(opts: { method: string; path: string }, handler: EndpointHandler): EndpointDefinition ``` Use `endpoint(...)` for custom HTTP routes (webhooks, REST). Response helpers: ```ts json(body: any, init?: { status?: number; headers?: Record }): EndpointResponse // → application/json, status 200 default text(body: string, init?: { status?: number; headers?: Record }): EndpointResponse // → text/plain, status 200 default ``` ### 3.7 Sockets and rate limits ```ts interface SocketLike { send(data: string): void close(code?: number, reason?: string): void on(event: "message", listener: (data: string) => void): void on(event: "close", listener: () => void): void } type SocketHandler = (ctx: CapsuleContext, socket: SocketLike) => void | Promise socket(handler: SocketHandler): SocketDefinition interface RouteRateLimit { perMinute?: number perHour?: number by?: "ip" | "user" // default "ip" } ``` `rateLimit[name]` applies to the query/mutation/endpoint of that name. Over-limit requests get `429` with `{ "error": "Rate limited" }` and `Retry-After: 60`. Buckets are rolling and in-process (reset on restart). --- ## 4. Client API contract (`pond/client`) All signatures below are taken verbatim from `client/index.ts`. ### 4.1 `useQuery` ```ts useQuery(name: string, ...args: TArgs): { data: T | undefined isLoading: boolean error: Error | null refetch: () => Promise } ``` Semantics: - **No args** ⇒ `GET /api/query/`. - **With args** ⇒ `POST /api/query/` with body `{"args":[...]}`. The args array is spread into the server handler after `ctx`. - **Args are the cache key.** The args are `JSON.stringify`-ed; when they change, the query refetches automatically (the empty-args key is `""`). - `data` is the most recent successful response (`undefined` before first load). - `isLoading` is `true` during the first load and during any refetch. - `error` is set when the last fetch threw and cleared on the next successful refetch. - An empty response body parses to `undefined` (mutations returning void). - A non-2xx response throws `Error: API error: `. - **Auto-refetch:** every active `useQuery` (across all components, keyed by the shared listener registry) refetches whenever **any** `useMutation` completes successfully. This is intentionally aggressive; capsules are small apps. ### 4.2 `useMutation` ```ts useMutation(name: string): [(...args: TArgs) => Promise, { isLoading: boolean; error: Error | null }] ``` - Returns `[run, state]`. `run(...args)` ⇒ `POST /api/mutation/` with body `{"args":[...]}` (positional args matching the server mutation). - On success it resolves with the parsed result **and** triggers a refetch of every active query. - On failure it sets `state.error` and re-throws. ### 4.3 `useAuth` ```ts interface AuthState { isLoading: boolean isGuest: boolean userId: string displayName?: string picture?: string email?: string } useAuth(): AuthState ``` Reads `GET /auth/me`. Default before load: `{ isLoading: true, isGuest: true, userId: "guest" }`. Listens for the `pond:auth-changed` window event and refetches when it fires. ### 4.4 `SignInWithGoogle` / `signOut` ```ts SignInWithGoogle(props?: Record): VNode // a
    {todos?.map((t) => (
  • toggleTodo(t.id)} /> {t.text}
    • ))}
) } ``` This example uses only `pond/server` / `pond/client` exports, exports `App`, keeps writes server-side, filters by `ctx.auth.userId`, re-checks ownership on `toggleTodo`, and uses only `string()` / `boolean()` columns — satisfying every item in the §7 checklist.