@pramen/server 0.0.1

package/dist/runtime/db.js

@@ -0,0 +1,425 @@
+// Db — the repository surface handed to handlers, wrapping the DO's in-process
+// SqlStorage. This is the single ACL chokepoint — all reads go through the read
+// engine: every find/insert/update/delete resolves a scope for the
+// caller's identity and is denied, row-filtered, or field-projected accordingly.
+//
+// Generic over the app's schema S: method inputs and results are typed against
+// the entity definitions (sdk/infer.ts). Types are erased at runtime — the body
+// works in terms of plain strings and Rows.
+//
+// Every Db also records the tables it touched during one handler run (`touched`),
+// which the live-query layer uses to decide which subscriptions to re-check.
+// Create a fresh Db per handler run so identity and `touched` are scoped.
+import { AclDenied, ALLOW_ALL, effectiveFields, projectRow, resolveRelationScope, resolveScope, resolveWriteRules, } from "./acl";
+import { and, cmp, compileAggregate, compileCount, compileExpr, compileSelect, compileWhere, eq, inList, or, TRUE, } from "./read-engine";
+import { BadRequest } from "./errors";
+const DEFAULT_PAGE_SIZE = 50;
+function normalizeOrder(orderBy) {
+    if (!orderBy)
+        return undefined;
+    return (Array.isArray(orderBy) ? orderBy : [orderBy]);
+}
+function encodeCursor(order, row) {
+    const vals = order.map((o) => row[o.column]);
+    return btoa(JSON.stringify(vals)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function decodeCursor(s) {
+    try {
+        const arr = JSON.parse(atob(s.replace(/-/g, "+").replace(/_/g, "/")));
+        if (!Array.isArray(arr))
+            throw new Error("not an array");
+        return arr;
+    }
+    catch {
+        throw new BadRequest("invalid cursor");
+    }
+}
+// Strictly-after predicate for a composite key: lexicographic comparison,
+// e.g. (a,b) after (a0,b0) => a>a0 OR (a=a0 AND b>b0); DESC columns flip to <.
+function keysetAfter(order, values) {
+    const ors = [];
+    for (let i = 0; i < order.length; i++) {
+        const parts = [];
+        for (let j = 0; j < i; j++)
+            parts.push(eq(order[j].column, values[j]));
+        const o = order[i];
+        parts.push(o.dir === "desc" ? cmp("<", o.column, values[i]) : cmp(">", o.column, values[i]));
+        ors.push(parts.length === 1 ? parts[0] : and(...parts));
+    }
+    return ors.length === 1 ? ors[0] : or(...ors);
+}
+export class Db {
+    driver;
+    acl;
+    schema;
+    /** Tables read or written during this Db's lifetime. */
+    touched = new Set();
+    dialect;
+    constructor(driver, acl, schema) {
+        this.driver = driver;
+        this.acl = acl;
+        this.schema = schema;
+        this.dialect = driver.dialect;
+    }
+    /** Resolve the ACL scope for an operation, or grant everything in SYSTEM mode. */
+    scopeFor(entity, action) {
+        if (this.acl.system)
+            return ALLOW_ALL;
+        return resolveScope(this.acl, entity, action);
+    }
+    /** Forced `set` values + validators for a write (empty in SYSTEM mode). The two
+     * halves are applied separately so the cell-level field check can run AFTER `set`
+     * (so a conditional `when` sees forced columns) but BEFORE `validate`. */
+    writeRules(entity, action) {
+        if (this.acl.system)
+            return { set: {}, validators: [] };
+        return resolveWriteRules(this.acl, entity, action);
+    }
+    /** Run write validators against the final values; a throw surfaces as a 400. */
+    runValidators(validators, values) {
+        for (const validate of validators) {
+            try {
+                validate({ identity: this.acl.identity, values });
+            }
+            catch (e) {
+                throw new BadRequest(e instanceof Error ? e.message : "validation failed");
+            }
+        }
+    }
+    /** Enforce field-level (incl. cell-level) write permission for one row. `setCols`
+     * are server-forced values that bypass the restriction. `evalRow` is the row the
+     * per-row grants are evaluated against (candidate on insert, post-merge on update). */
+    checkWriteFields(table, action, scope, writtenCols, evalRow, setCols) {
+        const allowed = effectiveFields(scope, evalRow, this.acl.identity);
+        if (!allowed)
+            return; // all fields permitted for this row
+        for (const c of writtenCols) {
+            if (!setCols.has(c) && !allowed.includes(c))
+                throw new AclDenied(table, action, c);
+        }
+    }
+    /** Reject ordering by a column the caller cannot read (closes an info-leak: order
+     * and the keyset cursor would otherwise expose a hidden column's values). Columns
+     * granted only conditionally are NOT orderable. */
+    assertReadableCols(from, scope, cols) {
+        if (scope.fields === null)
+            return;
+        for (const c of cols)
+            if (!scope.fields.includes(c))
+                throw new AclDenied(from, "read", c);
+    }
+    /** Structured read; ACL row-scope is AND-ed in, permitted fields projected.
+     * Selected relations are eager-loaded, each independently ACL-checked. */
+    async find(spec) {
+        const from = spec.from;
+        this.touched.add(from);
+        const scope = this.scopeFor(from, "read");
+        if (!scope.allowed)
+            throw new AclDenied(from, "read");
+        const where = this.readWhere(spec.where, scope);
+        const orderBy = normalizeOrder(spec.orderBy);
+        if (orderBy)
+            this.assertReadableCols(from, scope, orderBy.map((o) => o.column));
+        const raw = await this.selectRaw(from, where, orderBy, spec.limit, spec.offset);
+        return (await this.finishRows(from, raw, scope, spec.with));
+    }
+    /** Cursor (keyset) pagination. Stable under inserts/deletes; the PK is appended
+     * to `orderBy` as a tiebreaker so the keyset is unique. Returns the page plus an
+     * opaque `cursor` (pass back as `after`) and whether more rows remain. */
+    async page(spec) {
+        const from = spec.from;
+        this.touched.add(from);
+        const scope = this.scopeFor(from, "read");
+        if (!scope.allowed)
+            throw new AclDenied(from, "read");
+        const order = this.orderWithPk(from, spec.orderBy);
+        this.assertReadableCols(from, scope, order.map((o) => o.column)); // order + cursor must not leak hidden cols
+        let where = this.readWhere(spec.where, scope);
+        if (spec.after != null)
+            where = and(where, keysetAfter(order, decodeCursor(spec.after)));
+        const limit = spec.limit ?? DEFAULT_PAGE_SIZE;
+        const raw = await this.selectRaw(from, where, order, limit + 1); // +1 to detect a next page
+        const hasMore = raw.length > limit;
+        if (hasMore)
+            raw.length = limit;
+        const last = raw[raw.length - 1];
+        const cursor = last ? encodeCursor(order, last) : null; // from raw row (has all order cols)
+        const items = (await this.finishRows(from, raw, scope, spec.with));
+        return { items, cursor, hasMore };
+    }
+    /** Count rows visible to the caller (ACL read scope applied). */
+    async count(spec) {
+        const from = spec.from;
+        this.touched.add(from);
+        const scope = this.scopeFor(from, "read");
+        if (!scope.allowed)
+            throw new AclDenied(from, "read");
+        const where = this.readWhere(spec.where, scope);
+        const { sql, params } = compileCount(from, this.dialect, where);
+        const rows = (await this.driver.exec(sql, params));
+        return Number(rows[0]?.n ?? 0);
+    }
+    /** Grouped aggregation (count/sum/avg/min/max). ACL read scope is applied, and
+     * every referenced column must be readable under field permissions. The result
+     * row type is inferred from the spec: group columns keep their schema type and
+     * each aggregation gets its computed value type. */
+    async aggregate(spec) {
+        const from = spec.from;
+        this.touched.add(from);
+        const scope = this.scopeFor(from, "read");
+        if (!scope.allowed)
+            throw new AclDenied(from, "read");
+        const groupBy = (spec.groupBy ? (Array.isArray(spec.groupBy) ? spec.groupBy : [spec.groupBy]) : []);
+        // A json/fileRef cell is JSON; grouping/min/max over it would return the raw
+        // string (the codec only runs on row reads), so reject it rather than leak/lie.
+        const jsonCols = new Set(this.jsonColsOf(from));
+        for (const c of groupBy)
+            if (jsonCols.has(c))
+                throw new BadRequest(`cannot group by a json column: ${c}`);
+        for (const agg of Object.values(spec.aggregations)) {
+            if (agg.column && jsonCols.has(agg.column)) {
+                throw new BadRequest(`cannot aggregate a json column: ${agg.column}`);
+            }
+        }
+        if (scope.fields) {
+            const refs = new Set(groupBy);
+            for (const agg of Object.values(spec.aggregations))
+                if (agg.column)
+                    refs.add(agg.column);
+            for (const c of refs)
+                if (!scope.fields.includes(c))
+                    throw new AclDenied(from, "read", c);
+        }
+        const where = this.readWhere(spec.where, scope);
+        const { sql, params } = compileAggregate({ from, where, groupBy, aggregations: spec.aggregations }, this.dialect);
+        return (await this.driver.exec(sql, params));
+    }
+    // --- read internals shared by find/page ---
+    readWhere(userWhere, scope) {
+        const userExpr = userWhere ? compileWhere(userWhere) : TRUE;
+        return scope.where ? and(userExpr, scope.where) : userExpr;
+    }
+    async selectRaw(from, where, orderBy, limit, offset) {
+        const { sql, params } = compileSelect({ from, where, orderBy, limit, offset }, this.dialect);
+        return this.decodeRows(from, await this.driver.exec(sql, params));
+    }
+    // --- JSON codec: a `json` or `fileRef` column is stored as a JSON TEXT cell but
+    // handlers see/write the parsed value. Decode on read, encode (stringify) on write. ---
+    jsonColsOf(table) {
+        const fields = this.schema[table]?.fields;
+        if (!fields)
+            return [];
+        return Object.entries(fields)
+            .filter(([, f]) => f.type === "json" || f.type === "fileRef")
+            .map(([n]) => n);
+    }
+    decodeRows(table, rows) {
+        const cols = this.jsonColsOf(table);
+        if (cols.length === 0)
+            return rows;
+        for (const row of rows) {
+            for (const c of cols) {
+                const v = row[c];
+                if (typeof v === "string") {
+                    try {
+                        row[c] = JSON.parse(v);
+                    }
+                    catch {
+                        /* leave a non-JSON value as-is */
+                    }
+                }
+            }
+        }
+        return rows;
+    }
+    decodeRow(table, row) {
+        return row ? this.decodeRows(table, [row])[0] : row;
+    }
+    /** Encode one write cell: JSON-stringify a json/fileRef value, then dialect-encode. */
+    encodeCell(jsonCols, col, v) {
+        if (v != null && jsonCols.has(col))
+            return this.dialect.encode(JSON.stringify(v));
+        return this.dialect.encode(v);
+    }
+    /** Fetch one row by id within an ACL row-scope (for per-row write evaluation). */
+    async fetchOne(from, id, scopeWhere) {
+        const where = scopeWhere ? and(eq("id", id), scopeWhere) : eq("id", id);
+        const { sql, params } = compileSelect({ from, where, limit: 1 }, this.dialect);
+        return this.decodeRow(from, (await this.driver.exec(sql, params))[0]);
+    }
+    async finishRows(from, raw, scope, withSel) {
+        const relNames = withSel ? Object.keys(withSel).filter((k) => withSel[k]) : [];
+        for (const relName of relNames)
+            await this.loadRelation(from, raw, relName);
+        if (scope.fields === null)
+            return raw; // base unrestricted -> no per-row narrowing possible
+        return raw.map((r) => {
+            const projected = projectRow(r, effectiveFields(scope, r, this.acl.identity));
+            for (const relName of relNames)
+                projected[relName] = r[relName]; // relations survive projection
+            return projected;
+        });
+    }
+    orderWithPk(from, orderBy) {
+        const out = (normalizeOrder(orderBy) ?? []).map((o) => ({ column: o.column, dir: o.dir }));
+        const pk = this.pkOf(from);
+        if (!out.some((o) => o.column === pk))
+            out.push({ column: pk, dir: out[out.length - 1]?.dir ?? "asc" });
+        return out;
+    }
+    pkOf(from) {
+        const fields = this.schema[from]?.fields;
+        if (fields)
+            for (const [name, f] of Object.entries(fields))
+                if (f.primaryKey)
+                    return name;
+        return "id";
+    }
+    /** Eager-load one relation onto `rows` (mutates them). Traversal is ACL-checked
+     * via resolveRelationScope: the related read scope OR a parent directAccess grant. */
+    async loadRelation(parentEntity, rows, relName) {
+        const rel = this.schema[parentEntity]?.relations?.[relName];
+        if (!rel)
+            throw new Error(`unknown relation: ${parentEntity}.${relName}`);
+        this.touched.add(rel.target);
+        const scope = this.acl.system ? ALLOW_ALL : resolveRelationScope(this.acl, parentEntity, relName, rel.target);
+        if (!scope.allowed)
+            throw new AclDenied(rel.target, "read");
+        const project = (row) => projectRow(row, effectiveFields(scope, row, this.acl.identity));
+        // One IN query per relation (no N+1). Match column before projecting (which
+        // may drop the join column).
+        const fetchBy = async (col, values) => {
+            if (values.length === 0)
+                return [];
+            const where = scope.where ? and(inList(col, values), scope.where) : inList(col, values);
+            const { sql, params } = compileSelect({ from: rel.target, where }, this.dialect);
+            const rows = this.decodeRows(rel.target, await this.driver.exec(sql, params));
+            return rows.map((row) => ({ key: row[col], row: project(row) }));
+        };
+        if (rel.kind === "belongsTo") {
+            // parent[column] -> target.id
+            const keys = [...new Set(rows.map((r) => r[rel.column]).filter((v) => v != null))];
+            const byId = new Map();
+            for (const { key, row } of await fetchBy("id", keys))
+                byId.set(key, row);
+            for (const r of rows)
+                r[relName] = r[rel.column] != null ? (byId.get(r[rel.column]) ?? null) : null;
+        }
+        else {
+            // hasMany: target[column] -> parent.id
+            const ids = [...new Set(rows.map((r) => r.id).filter((v) => v != null))];
+            const grouped = new Map();
+            for (const { key, row } of await fetchBy(rel.column, ids)) {
+                const bucket = grouped.get(key) ?? grouped.set(key, []).get(key);
+                bucket.push(row);
+            }
+            for (const r of rows)
+                r[relName] = grouped.get(r.id) ?? [];
+        }
+    }
+    /** Insert a single row, returning the persisted row. */
+    async insert(table, values) {
+        this.touched.add(table);
+        const scope = this.scopeFor(table, "create");
+        if (!scope.allowed)
+            throw new AclDenied(table, "create");
+        const vals = { ...values };
+        const { set, validators } = this.writeRules(table, "create");
+        Object.assign(vals, set); // forced server values first, so a conditional `when` can see them
+        this.checkWriteFields(table, "create", scope, Object.keys(vals), vals, new Set(Object.keys(set)));
+        this.runValidators(validators, vals);
+        const cols = Object.keys(vals);
+        const jsonCols = new Set(this.jsonColsOf(table));
+        const colList = cols.map((c) => this.dialect.id(c)).join(", ");
+        const phs = cols.map((_, i) => this.dialect.placeholder(i + 1)).join(", ");
+        const params = cols.map((c) => this.encodeCell(jsonCols, c, vals[c]));
+        const sql = `INSERT INTO ${this.dialect.id(table)} (${colList}) VALUES (${phs})${this.returningClause("*")}`;
+        const rows = await this.driver.exec(sql, params);
+        return this.projectWrite(table, this.decodeRow(table, rows[0]), cols);
+    }
+    /** Project a mutation's RETURNING row so the echo never reveals more than a read
+     * would: the caller's readable fields for this row, PLUS the columns they just
+     * wrote (which they already know) and the primary key (so a write-only caller
+     * still gets the generated id). Full read access -> the whole row; SYSTEM -> as-is.
+     * This makes create/update echoes field-ACL-safe without ever collapsing to {}. */
+    projectWrite(table, row, writtenCols) {
+        if (this.acl.system)
+            return row;
+        const visible = new Set([this.pkOf(table), ...writtenCols]);
+        const readScope = this.scopeFor(table, "read");
+        if (readScope.allowed) {
+            const readable = effectiveFields(readScope, row, this.acl.identity);
+            if (readable === null)
+                return row; // unrestricted read -> echo everything
+            for (const f of readable)
+                visible.add(f);
+        }
+        return projectRow(row, [...visible]);
+    }
+    /** Update a row by id. ACL row-scope is AND-ed into the WHERE, so a caller can
+     * only update rows within scope; returns undefined if none matched. */
+    async update(table, id, patch) {
+        this.touched.add(table);
+        const scope = this.scopeFor(table, "update");
+        if (!scope.allowed)
+            throw new AclDenied(table, "update");
+        const p = { ...patch };
+        const { set, validators } = this.writeRules(table, "update");
+        Object.assign(p, set); // forced server values first
+        const cols = Object.keys(p);
+        if (cols.length === 0)
+            return undefined;
+        // Per-row field permission is evaluated against the FINAL (post-merge) row, so
+        // fetch the existing row within update scope when any cell-level rule applies.
+        let evalRow = p;
+        if (scope.fields !== null && (scope.conditional.length > 0 || scope.fieldsFns.length > 0)) {
+            const existing = await this.fetchOne(table, id, scope.where);
+            if (!existing)
+                return undefined; // out of update scope -> no-op
+            evalRow = { ...existing, ...p };
+        }
+        this.checkWriteFields(table, "update", scope, cols, evalRow, new Set(Object.keys(set)));
+        this.runValidators(validators, p);
+        const params = [];
+        const jsonCols = new Set(this.jsonColsOf(table));
+        const assignments = cols
+            .map((c) => {
+            params.push(this.encodeCell(jsonCols, c, p[c]));
+            return `${this.dialect.id(c)} = ${this.dialect.placeholder(params.length)}`;
+        })
+            .join(", ");
+        params.push(this.dialect.encode(id));
+        let sql = `UPDATE ${this.dialect.id(table)} SET ${assignments} WHERE ${this.dialect.id("id")} = ${this.dialect.placeholder(params.length)}`;
+        sql += this.scopeClause(scope.where, params);
+        sql += this.returningClause("*");
+        const updated = this.decodeRow(table, (await this.driver.exec(sql, params))[0]);
+        return (updated ? this.projectWrite(table, updated, cols) : undefined);
+    }
+    /** Delete a row by id within scope. Returns whether a row was deleted. */
+    async delete(table, id) {
+        this.touched.add(table);
+        const scope = this.scopeFor(table, "delete");
+        if (!scope.allowed)
+            throw new AclDenied(table, "delete");
+        const params = [this.dialect.encode(id)];
+        let sql = `DELETE FROM ${this.dialect.id(table)} WHERE ${this.dialect.id("id")} = ${this.dialect.placeholder(1)}`;
+        sql += this.scopeClause(scope.where, params);
+        sql += this.returningClause("id");
+        return (await this.driver.exec(sql, params)).length > 0;
+    }
+    /** Escape hatch — raw SQL, NOT ACL-checked. For system/internal use only. */
+    async exec(sql, ...params) {
+        return this.driver.exec(sql, params.map((p) => this.dialect.encode(p)));
+    }
+    // RETURNING is supported on SQLite/Postgres; a dialect without it (MySQL) would
+    // need an insert-then-select-back path — not implemented in this spike.
+    returningClause(cols) {
+        return this.dialect.returning ? ` RETURNING ${cols}` : "";
+    }
+    scopeClause(where, params) {
+        if (!where)
+            return "";
+        const compiled = compileExpr(where, this.dialect, params);
+        return compiled.sql === "1" ? "" : ` AND (${compiled.sql})`;
+    }
+}

package/dist/runtime/ddl.d.ts

@@ -0,0 +1,16 @@
+import type { EntityFields, FieldDef } from "../sdk/schema";
+export declare const sqlType: (f: FieldDef) => string;
+export declare function createTableSql(table: string, def: {
+    fields: EntityFields;
+}): string;
+/** Column definition for ALTER TABLE ADD COLUMN. No PRIMARY KEY / AUTOINCREMENT.
+ * NOT NULL is only emitted alongside a DEFAULT (SQLite can't add a bare NOT NULL to
+ * a populated table); a DEFAULT alone backfills existing rows. */
+export declare function addColumnSql(name: string, f: FieldDef): string;
+/** Index name for a column's unique/index constraint. */
+export declare function indexName(table: string, col: string): string;
+/** CREATE [UNIQUE] INDEX statements for a table's unique/index columns (idempotent
+ * via IF NOT EXISTS). Unique wins if a column declares both. */
+export declare function indexStatements(table: string, def: {
+    fields: EntityFields;
+}): string[];

package/dist/runtime/ddl.js

@@ -0,0 +1,64 @@
+// DDL generation — CREATE TABLE for a new entity and the additive ALTER fragment
+// for a new column. Runs in TS inside the isolate; see runtime/migrate.ts for how
+// these are applied.
+// SQLite has no boolean type; store as INTEGER 0/1. json + fileRef are stored as
+// TEXT (JSON). Exported for the migrator, which compares declared column types
+// (and CASTs on a type change).
+export const sqlType = (f) => f.type === "boolean" ? "INTEGER" : f.type === "json" || f.type === "fileRef" ? "TEXT" : f.type.toUpperCase();
+/** Render a DEFAULT literal. Strings are single-quote-escaped; booleans → 0/1. */
+function defaultLiteral(v) {
+    if (v === null)
+        return "NULL";
+    if (typeof v === "boolean")
+        return v ? "1" : "0";
+    if (typeof v === "number")
+        return String(v);
+    return `'${v.replace(/'/g, "''")}'`;
+}
+/** The ` DEFAULT x` fragment for a column, or "" when it has no default. UNIQUE/
+ * index are NOT inline — they're emitted as separate index statements so the same
+ * code path serves both CREATE TABLE and ALTER TABLE ADD COLUMN. */
+function defaultSql(f) {
+    return f.default !== undefined ? ` DEFAULT ${defaultLiteral(f.default)}` : "";
+}
+function columnSql(name, f) {
+    let s = `${name} ${sqlType(f)}`;
+    if (f.primaryKey)
+        s += " PRIMARY KEY";
+    if (f.autoIncrement)
+        s += " AUTOINCREMENT";
+    if (f.notNull && !f.primaryKey)
+        s += " NOT NULL";
+    s += defaultSql(f);
+    return s;
+}
+export function createTableSql(table, def) {
+    const cols = Object.entries(def.fields).map(([n, f]) => columnSql(n, f));
+    return `CREATE TABLE IF NOT EXISTS ${table} (${cols.join(", ")})`;
+}
+/** Column definition for ALTER TABLE ADD COLUMN. No PRIMARY KEY / AUTOINCREMENT.
+ * NOT NULL is only emitted alongside a DEFAULT (SQLite can't add a bare NOT NULL to
+ * a populated table); a DEFAULT alone backfills existing rows. */
+export function addColumnSql(name, f) {
+    let s = `${name} ${sqlType(f)}`;
+    if (f.notNull && f.default !== undefined)
+        s += " NOT NULL";
+    s += defaultSql(f);
+    return s;
+}
+/** Index name for a column's unique/index constraint. */
+export function indexName(table, col) {
+    return `pramen_idx_${table}_${col}`;
+}
+/** CREATE [UNIQUE] INDEX statements for a table's unique/index columns (idempotent
+ * via IF NOT EXISTS). Unique wins if a column declares both. */
+export function indexStatements(table, def) {
+    const out = [];
+    for (const [col, f] of Object.entries(def.fields)) {
+        if (!f.unique && !f.index)
+            continue;
+        const kind = f.unique ? "UNIQUE INDEX" : "INDEX";
+        out.push(`CREATE ${kind} IF NOT EXISTS ${indexName(table, col)} ON ${table} (${col})`);
+    }
+    return out;
+}

package/dist/runtime/digest.d.ts

@@ -0,0 +1 @@
+export declare function digest(result: unknown): string;

package/dist/runtime/digest.js

@@ -0,0 +1,29 @@
+// Stable digest of a query result, for row-level change detection. Two results
+// that are deeply equal (modulo object key order) hash the same, so a mutation
+// that doesn't change a given subscription's visible rows produces no push.
+//
+// Re-running the query is cheap (in-process SQLite); the digest gates the
+// expensive part — the network push and the client re-render.
+function canonical(v) {
+    if (v === null || typeof v !== "object")
+        return JSON.stringify(v) ?? "null";
+    if (Array.isArray(v))
+        return "[" + v.map(canonical).join(",") + "]";
+    const obj = v;
+    return ("{" +
+        Object.keys(obj)
+            .sort()
+            .map((k) => JSON.stringify(k) + ":" + canonical(obj[k]))
+            .join(",") +
+        "}");
+}
+export function digest(result) {
+    const s = canonical(result);
+    // FNV-1a (32-bit).
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+    }
+    return h.toString(16);
+}

package/dist/runtime/dispatch.d.ts

@@ -0,0 +1,12 @@
+import { type AclContext } from "./acl";
+import type { Driver } from "./driver";
+import type { Kv } from "./kv";
+import type { Files } from "../sdk/files";
+import type { SchemaDef } from "../sdk/schema";
+import type { HandlerKind, HandlerMap } from "../sdk/handlers";
+export interface DispatchResult {
+    readonly result: unknown;
+    readonly kind: HandlerKind;
+    readonly touched: string[];
+}
+export declare function dispatch(handlers: HandlerMap, schema: SchemaDef, driver: Driver, kv: Kv, files: Files, env: Readonly<Record<string, unknown>>, acl: AclContext, name: string, input: unknown): Promise<DispatchResult>;

package/dist/runtime/dispatch.js

@@ -0,0 +1,37 @@
+// Dispatch — resolves a handler by name and runs it with a fresh, ACL-scoped Db.
+// Mutations run inside storage.transaction(), which commits on success and rolls
+// back on throw — the platform-correct way to auto-wrap mutations in BEGIN/COMMIT.
+// (DO SQLite rejects raw BEGIN/COMMIT because it does atomic write coalescing under
+// this API.) Single-writer serialization is free:
+// a Durable Object processes one request at a time.
+//
+// The result reports `touched` (tables the run read or wrote) so the live-query
+// layer can match a mutation's writes against each subscription's reads.
+import { Db } from "./db";
+import { warmup } from "./acl";
+import { BadRequest } from "./errors";
+export async function dispatch(handlers, schema, driver, kv, files, env, acl, name, input) {
+    const handler = handlers[name];
+    if (!handler)
+        throw new BadRequest(`unknown handler: ${name}`);
+    // Validate/parse the request input at the boundary, if the handler declares it.
+    let parsed = input;
+    if (handler.input) {
+        try {
+            parsed = handler.input(input);
+        }
+        catch (e) {
+            throw new BadRequest(e instanceof Error ? e.message : "invalid input");
+        }
+    }
+    // Warmup: evaluate dynamic resolvers once, reading through a SYSTEM-mode db
+    // (separate from the handler's db, so its reads don't pollute `touched`).
+    const systemDb = new Db(driver, { acl: acl.acl, identity: acl.identity, system: true }, schema);
+    const resolved = await warmup(acl.acl, acl.identity, systemDb);
+    const db = new Db(driver, { acl: acl.acl, identity: acl.identity, input: parsed, resolved }, schema);
+    const ctx = { db, kv, files, env, identity: acl.identity };
+    const result = handler.kind === "query"
+        ? await handler.run(ctx, parsed)
+        : await driver.transaction(async () => handler.run(ctx, parsed));
+    return { result, kind: handler.kind, touched: [...db.touched] };
+}

package/dist/runtime/driver.d.ts

@@ -0,0 +1,45 @@
+export type Row = Record<string, unknown>;
+export interface Dialect {
+    /** Render an identifier (table/column), quoting as the backend requires. */
+    id(name: string): string;
+    /** Bind placeholder for the `n`-th parameter (1-based): `?` (SQLite/MySQL) or `$n` (Postgres). */
+    placeholder(n: number): string;
+    /** Whether INSERT/UPDATE/DELETE ... RETURNING is supported (SQLite/Postgres yes; MySQL no). */
+    readonly returning: boolean;
+    /** Coerce a JS value for binding (e.g. boolean → 0/1 on SQLite). */
+    encode(v: unknown): unknown;
+}
+/** SQLite (DO SQLite and D1 both speak this). Bare identifiers, `?` placeholders,
+ * booleans stored as INTEGER 0/1, RETURNING supported. */
+export declare const sqliteDialect: Dialect;
+/** Postgres (e.g. over Hyperdrive). Double-quoted identifiers preserve case (so
+ * `ownerId` doesn't fold to `ownerid`), `$n` placeholders, native booleans,
+ * RETURNING supported. */
+export declare const postgresDialect: Dialect;
+export interface Driver {
+    readonly dialect: Dialect;
+    /** Run a parameterized statement and return the result rows (empty for writes
+     * without RETURNING). Params are already dialect-encoded by the caller. */
+    exec(sql: string, params: unknown[]): Promise<Row[]>;
+    /** Run `fn` inside a transaction: commit on resolve, roll back on throw. */
+    transaction<T>(fn: () => Promise<T>): Promise<T>;
+}
+/** DO SQLite — the in-process store. `SqlStorage` is synchronous; we wrap it as an
+ * async Driver. Transactions use the DO's atomic `transaction()`. */
+export declare class DoSqliteDriver implements Driver {
+    private readonly storage;
+    readonly dialect: Dialect;
+    constructor(storage: DurableObjectStorage);
+    exec(sql: string, params: unknown[]): Promise<Row[]>;
+    transaction<T>(fn: () => Promise<T>): Promise<T>;
+}
+/** D1 — SQLite over RPC. Async by nature. D1 has no interactive transactions, so
+ * `transaction()` runs `fn` without one (a documented limitation: mutations don't
+ * roll back on throw the way they do on a DO). Use a DO when you need that. */
+export declare class D1Driver implements Driver {
+    private readonly db;
+    readonly dialect: Dialect;
+    constructor(db: D1Database);
+    exec(sql: string, params: unknown[]): Promise<Row[]>;
+    transaction<T>(fn: () => Promise<T>): Promise<T>;
+}