@pramen/server 0.0.1

package/dist/runtime/read-engine.js

@@ -0,0 +1,219 @@
+// 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.
+// 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) {
+    return typeof v === "boolean" ? (v ? 1 : 0) : v;
+}
+export const TRUE = { t: "true" };
+export const FALSE = { t: "false" };
+export const cmp = (op, col, value) => ({ t: "cmp", op, col, value });
+export const isNull = (col, negate = false) => ({ t: "null", col, negate });
+export const inList = (col, values, negate = false) => ({ t: "in", col, values, negate });
+export const and = (...parts) => ({ t: "and", parts });
+export const or = (...parts) => ({ t: "or", parts });
+/** Equality (null -> IS NULL). Used by ACL scope building and relation loads. */
+export const eq = (col, value) => (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) {
+    const parts = [];
+    for (const [k, v] of Object.entries(input)) {
+        if (k === "AND") {
+            parts.push(and(...v.map(compileWhere)));
+        }
+        else if (k === "OR") {
+            parts.push(or(...v.map(compileWhere)));
+        }
+        else {
+            parts.push(columnPredicate(k, v));
+        }
+    }
+    return parts.length ? and(...parts) : TRUE;
+}
+function columnPredicate(col, v) {
+    if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+        const ops = [];
+        for (const [op, val] of Object.entries(v)) {
+            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));
+                    break;
+                case "notIn":
+                    ops.push(inList(col, val, 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 function compileExpr(expr, dialect, params = []) {
+    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) {
+    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, row) {
+    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 > right;
+                case ">=": return left >= right;
+                case "<": return left < right;
+                case "<=": return left <= right;
+                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));
+    }
+}
+const AGG_SQL = { count: "COUNT", sum: "SUM", avg: "AVG", min: "MIN", max: "MAX" };
+export function compileCount(from, dialect, where) {
+    const params = [];
+    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 function compileAggregate(spec, dialect) {
+    const params = [];
+    const cols = [];
+    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, dialect) {
+    const params = [];
+    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/dist/runtime/schema-diff.d.ts

@@ -0,0 +1,14 @@
+import type { SchemaDef } from "../sdk/schema";
+/** table -> column -> field type. The comparable surface of a schema. */
+export type SchemaShape = Record<string, Record<string, string>>;
+export declare function schemaShape(schema: SchemaDef): SchemaShape;
+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 declare function diffSchemaShape(prev: SchemaShape, next: SchemaShape): SchemaChange[];

package/dist/runtime/schema-diff.js

@@ -0,0 +1,41 @@
+// 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.
+export function schemaShape(schema) {
+    const out = {};
+    for (const [table, def] of Object.entries(schema)) {
+        const cols = {};
+        for (const [col, f] of Object.entries(def.fields))
+            cols[col] = f.type;
+        out[table] = cols;
+    }
+    return out;
+}
+export function diffSchemaShape(prev, next) {
+    const changes = [];
+    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/dist/runtime/storage.d.ts

@@ -0,0 +1,74 @@
+import type { Files, HeadResult } from "../sdk/files";
+export type { Files, FileRef, HeadResult, SignDownloadOpts, SignUploadOpts } from "../sdk/files";
+export interface PutResult {
+    key: string;
+    size: number;
+    etag?: string;
+}
+export interface GetResult {
+    body: ReadableStream;
+    size: number;
+    contentType?: string;
+}
+export interface StorageAdapter {
+    put(key: string, body: ReadableStream | ArrayBuffer | Uint8Array | null, opts?: {
+        contentType?: string;
+    }): Promise<PutResult>;
+    get(key: string): Promise<GetResult | null>;
+    head(key: string): Promise<HeadResult | null>;
+    delete(key: string): Promise<void>;
+}
+/** R2 — the Cloudflare default. Wraps an R2 bucket binding. Streaming: bytes flow
+ * directly between the client and R2 in the Worker, never through the DO. */
+export declare class R2Adapter implements StorageAdapter {
+    private readonly bucket;
+    constructor(bucket: R2Bucket);
+    put(key: string, body: ReadableStream | ArrayBuffer | Uint8Array | null, opts?: {
+        contentType?: string;
+    }): Promise<PutResult>;
+    get(key: string): Promise<GetResult | null>;
+    head(key: string): Promise<HeadResult | null>;
+    delete(key: string): Promise<void>;
+}
+/** In-memory store for unit tests / substrates without an object store. Not durable. */
+export declare class MemoryAdapter implements StorageAdapter {
+    private readonly store;
+    put(key: string, body: ReadableStream | ArrayBuffer | Uint8Array | null, opts?: {
+        contentType?: string;
+    }): Promise<PutResult>;
+    get(key: string): Promise<GetResult | null>;
+    head(key: string): Promise<HeadResult | null>;
+    delete(key: string): Promise<void>;
+}
+interface FileToken {
+    /** tenant */ t: string;
+    /** key */ k: string;
+    /** op */ op: "get" | "put";
+    /** expiry (epoch seconds) */ exp: number;
+    /** content-type (put: enforced; get: disposition hint) */ ct?: string;
+    /** max size in bytes (put only) */ max?: number;
+    /** filename (download disposition) */ fn?: string;
+}
+/** Verify a file token's signature + expiry; returns the payload or null. */
+export declare function verifyToken(raw: string, secret: string): Promise<FileToken | null>;
+export interface FilesConfig {
+    tenant: string;
+    secret: string;
+    adapter: StorageAdapter;
+    /** Worker base path for file endpoints (default "/files"). */
+    basePath?: string;
+}
+/** A file token secret must be present and non-trivial, else upload/download tokens
+ * would be forgeable (HMAC over an empty/weak key). Below this, file storage is
+ * treated as unconfigured — fail closed rather than mint forgeable urls. The dev
+ * defaults satisfy it; production should set a strong, random FILES_SECRET. */
+export declare const MIN_FILES_SECRET_LEN = 16;
+export declare function isUsableFilesSecret(secret: string | undefined | null): secret is string;
+/** Construct the per-tenant `ctx.files` facade. */
+export declare function createFiles(cfg: FilesConfig): Files;
+/** Serve the file endpoints. Returns a Response for any `/files/*` path, or null
+ * if the request is not a file request (so the caller can keep routing). */
+export declare function handleFileRequest(request: Request, opts: {
+    adapter: StorageAdapter;
+    secret: string;
+}): Promise<Response | null>;

package/dist/sdk/acl.d.ts

@@ -0,0 +1,130 @@
+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;
+}
+declare const IDENTITY_MARKER: unique symbol;
+export interface IdentityMarker {
+    readonly [IDENTITY_MARKER]: true;
+    readonly path: string;
+}
+/** Reference an identity property in a policy `where`, resolved per request. */
+export declare function $identity(path: string): IdentityMarker;
+export declare function isIdentityMarker(v: unknown): v is IdentityMarker;
+declare const INPUT_MARKER: unique symbol;
+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 declare function $input(path: string): InputMarker;
+export declare function isInputMarker(v: unknown): v is InputMarker;
+export interface AllowMarker {
+    readonly kind: "allow";
+}
+export interface DenyMarker {
+    readonly kind: "deny";
+}
+export declare function allow(): AllowMarker;
+export declare function deny(): DenyMarker;
+/** 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;
+}
+/** 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;
+}
+/** A policy rule evaluated once per request during warmup; returns allow/deny/rules. */
+export declare function resolve(fn: ResolverFn): ResolverMarker;
+export type PolicyRule = AllowMarker | DenyMarker | PolicyRules | ResolverMarker;
+export interface Policy {
+    readonly name: string;
+    readonly entity: string;
+    readonly action: Action;
+    readonly rule: PolicyRule;
+}
+export declare function policy(name: string, entity: string, action: Action, rule: PolicyRule): Policy;
+export interface Role {
+    readonly name: string;
+    readonly policies: Policy[];
+}
+export declare function role(name: string, policies: Policy[]): Role;
+export declare function isAllow(r: PolicyRule): r is AllowMarker;
+export declare function isDeny(r: PolicyRule): r is DenyMarker;
+export declare function isResolver(r: PolicyRule): r is ResolverMarker;
+export {};

package/dist/sdk/acl.js

@@ -0,0 +1,55 @@
+// 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).
+// --- $identity markers: reference an identity property inside a where rule ---
+const IDENTITY_MARKER = Symbol.for("pramen.identityMarker");
+/** Reference an identity property in a policy `where`, resolved per request. */
+export function $identity(path) {
+    return { [IDENTITY_MARKER]: true, path };
+}
+export function isIdentityMarker(v) {
+    return typeof v === "object" && v !== null && v[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");
+/** 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) {
+    return { [INPUT_MARKER]: true, path };
+}
+export function isInputMarker(v) {
+    return typeof v === "object" && v !== null && v[INPUT_MARKER] === true;
+}
+export function allow() {
+    return { kind: "allow" };
+}
+export function deny() {
+    return { kind: "deny" };
+}
+let resolverCounter = 0;
+/** A policy rule evaluated once per request during warmup; returns allow/deny/rules. */
+export function resolve(fn) {
+    return { kind: "resolver", id: resolverCounter++, fn };
+}
+export function policy(name, entity, action, rule) {
+    return { name, entity, action, rule };
+}
+export function role(name, policies) {
+    return { name, policies };
+}
+export function isAllow(r) {
+    return r.kind === "allow";
+}
+export function isDeny(r) {
+    return r.kind === "deny";
+}
+export function isResolver(r) {
+    return r.kind === "resolver";
+}

package/dist/sdk/app.d.ts

@@ -0,0 +1,7 @@
+import type { Handler, HandlerContext, HandlerOpts } from "./handlers";
+import type { SchemaDef } from "./schema";
+export declare function createApp<S extends SchemaDef>(schema: S): {
+    schema: S;
+    query: <I = unknown, O = unknown>(run: (ctx: HandlerContext<S>, input: I) => O | Promise<O>, opts?: HandlerOpts<I>) => Handler<I, O>;
+    mutation: <I = unknown, O = unknown>(run: (ctx: HandlerContext<S>, input: I) => O | Promise<O>, opts?: HandlerOpts<I>) => Handler<I, O>;
+};

package/dist/sdk/app.js

@@ -0,0 +1,11 @@
+// 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!
+export function createApp(schema) {
+    const query = (run, opts) => ({ kind: "query", run: run, input: opts?.input });
+    const mutation = (run, opts) => ({ kind: "mutation", run: run, input: opts?.input });
+    return { schema, query, mutation };
+}

package/dist/sdk/files.d.ts

@@ -0,0 +1,51 @@
+/** 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/dist/sdk/files.js

@@ -0,0 +1,4 @@
+// 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.
+export {};

package/dist/sdk/handlers.d.ts

@@ -0,0 +1,36 @@
+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;
+    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;
+}
+export declare function query<I = unknown, O = unknown>(run: (ctx: HandlerContext, input: I) => O | Promise<O>, opts?: HandlerOpts<I>): Handler<I, O>;
+export declare function mutation<I = unknown, O = unknown>(run: (ctx: HandlerContext, input: I) => O | Promise<O>, opts?: HandlerOpts<I>): Handler<I, O>;
+export type HandlerMap = Record<string, Handler<any, any>>;

package/dist/sdk/handlers.js

@@ -0,0 +1,11 @@
+// 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).
+// Standalone (schema-agnostic) handler factories. Prefer createApp(schema) for a
+// typed ctx.db; these remain for untyped/ad-hoc use.
+export function query(run, opts) {
+    return { kind: "query", run, input: opts?.input };
+}
+export function mutation(run, opts) {
+    return { kind: "mutation", run, input: opts?.input };
+}