@pramen/server 0.0.1

package/dist/runtime/driver.js

@@ -0,0 +1,70 @@
+// Driver + Dialect — the substrate seam. pramen's ACL, read-engine, repository, and
+// migrator are written against these two interfaces, so the same data layer runs
+// over any SQL backend:
+//
+//   - Driver  : how to execute SQL and run a transaction (async). One per backend
+//               (DO SQLite, D1, Hyperdrive→Postgres, …).
+//   - Dialect : how a backend spells SQL (identifier quoting, bind placeholders,
+//               RETURNING support, value encoding). One per SQL flavor.
+//
+// This makes "Worker + D1" or "Worker + Hyperdrive/Postgres" a matter of plugging
+// in a Driver, rather than rewriting the engine. Live queries remain a DO-only
+// capability (they need a single writer + a stateful socket host).
+const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+// Column/table names come from developer schema keys (and validated `where` keys),
+// never raw user input — but we still guard the identifier shape before interpolating.
+function checkIdent(name) {
+    if (!IDENT_RE.test(name))
+        throw new Error(`invalid identifier: ${name}`);
+    return name;
+}
+/** SQLite (DO SQLite and D1 both speak this). Bare identifiers, `?` placeholders,
+ * booleans stored as INTEGER 0/1, RETURNING supported. */
+export const sqliteDialect = {
+    id: checkIdent,
+    placeholder: () => "?",
+    returning: true,
+    encode: (v) => (typeof v === "boolean" ? (v ? 1 : 0) : v),
+};
+/** Postgres (e.g. over Hyperdrive). Double-quoted identifiers preserve case (so
+ * `ownerId` doesn't fold to `ownerid`), `$n` placeholders, native booleans,
+ * RETURNING supported. */
+export const postgresDialect = {
+    id: (name) => `"${checkIdent(name)}"`,
+    placeholder: (n) => `$${n}`,
+    returning: true,
+    encode: (v) => v, // the pg driver handles type encoding
+};
+/** DO SQLite — the in-process store. `SqlStorage` is synchronous; we wrap it as an
+ * async Driver. Transactions use the DO's atomic `transaction()`. */
+export class DoSqliteDriver {
+    storage;
+    dialect = sqliteDialect;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    async exec(sql, params) {
+        return this.storage.sql.exec(sql, ...params).toArray();
+    }
+    transaction(fn) {
+        return this.storage.transaction(fn);
+    }
+}
+/** 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 class D1Driver {
+    db;
+    dialect = sqliteDialect;
+    constructor(db) {
+        this.db = db;
+    }
+    async exec(sql, params) {
+        const stmt = params.length ? this.db.prepare(sql).bind(...params) : this.db.prepare(sql);
+        const { results } = await stmt.all();
+        return results ?? [];
+    }
+    transaction(fn) {
+        return fn();
+    }
+}

package/dist/runtime/errors.d.ts

@@ -0,0 +1,34 @@
+export declare class PramenError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(message: string, status: number, code: string);
+}
+export declare class BadRequest extends PramenError {
+    constructor(message: string);
+}
+/** 401 — the caller is unauthenticated (no/invalid identity). */
+export declare class Unauthorized extends PramenError {
+    constructor(message?: string);
+}
+/** 403 — authenticated but not permitted. For handler-level checks; the Db
+ * chokepoint raises AclDenied for row/field ACL. */
+export declare class Forbidden extends PramenError {
+    constructor(message?: string);
+}
+export interface ErrorBody {
+    ok: false;
+    error: string;
+    code: string;
+}
+declare function classify(err: unknown): {
+    status: number;
+    body: ErrorBody;
+};
+export declare const toResponse: typeof classify;
+export declare function toWsError(id: string, err: unknown): {
+    type: "error";
+    id: string;
+    error: string;
+    code: string;
+};
+export {};

package/dist/runtime/errors.js

@@ -0,0 +1,43 @@
+// Error model. Anything that is the *client's* fault carries a status + code and
+// a message safe to return. Everything else is logged server-side and surfaced as
+// a generic 500 — internal messages / stack traces never reach the client.
+export class PramenError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "PramenError";
+    }
+}
+export class BadRequest extends PramenError {
+    constructor(message) {
+        super(message, 400, "bad_request");
+    }
+}
+/** 401 — the caller is unauthenticated (no/invalid identity). */
+export class Unauthorized extends PramenError {
+    constructor(message = "authentication required") {
+        super(message, 401, "unauthorized");
+    }
+}
+/** 403 — authenticated but not permitted. For handler-level checks; the Db
+ * chokepoint raises AclDenied for row/field ACL. */
+export class Forbidden extends PramenError {
+    constructor(message = "forbidden") {
+        super(message, 403, "forbidden");
+    }
+}
+function classify(err) {
+    if (err instanceof PramenError) {
+        return { status: err.status, body: { ok: false, error: err.message, code: err.code } };
+    }
+    console.error("pramen: unhandled error", err);
+    return { status: 500, body: { ok: false, error: "internal error", code: "internal" } };
+}
+export const toResponse = classify;
+export function toWsError(id, err) {
+    const { body } = classify(err);
+    return { type: "error", id, error: body.error, code: body.code };
+}

package/dist/runtime/kv.d.ts

@@ -0,0 +1,23 @@
+export declare class Kv {
+    private readonly ns;
+    private readonly prefix;
+    constructor(ns: KVNamespace, prefix?: string);
+    private full;
+    get(key: string): Promise<string | null>;
+    get(key: string, type: "json"): Promise<unknown>;
+    put(key: string, value: string, opts?: {
+        expirationTtl?: number;
+        expiration?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** List keys under an (app-relative) prefix; returned names have the internal
+     * prefix stripped. cursor is null when the listing is complete. */
+    list(opts?: {
+        prefix?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        keys: string[];
+        cursor: string | null;
+    }>;
+}

package/dist/runtime/kv.js

@@ -0,0 +1,41 @@
+// Kv — a thin, prefixed wrapper over the project's Workers KV namespace, handed
+// to handlers as ctx.kv.
+//
+// Two levels of namespacing keep things isolated:
+//  - Across projects: each project declares its own KV namespace in oblaka.ts
+//    (named per project), so projects in one account never share a namespace.
+//  - Within the namespace: keys are prefixed (`app:` for handler data) so they
+//    never collide with pramen-internal keys (the tenant registry uses `tenant:`).
+//
+// ctx.kv is GLOBAL across all tenants of the project — use it for config, feature
+// flags, and caches, NOT per-tenant data (that's ctx.db). KV is eventually
+// consistent and is NOT part of a mutation's transaction.
+export class Kv {
+    ns;
+    prefix;
+    constructor(ns, prefix = "app:") {
+        this.ns = ns;
+        this.prefix = prefix;
+    }
+    full(key) {
+        return this.prefix + key;
+    }
+    get(key, type) {
+        return type === "json" ? this.ns.get(this.full(key), "json") : this.ns.get(this.full(key), "text");
+    }
+    async put(key, value, opts) {
+        await this.ns.put(this.full(key), value, opts);
+    }
+    async delete(key) {
+        await this.ns.delete(this.full(key));
+    }
+    /** List keys under an (app-relative) prefix; returned names have the internal
+     * prefix stripped. cursor is null when the listing is complete. */
+    async list(opts) {
+        const res = await this.ns.list({ prefix: this.full(opts?.prefix ?? ""), limit: opts?.limit, cursor: opts?.cursor });
+        return {
+            keys: res.keys.map((k) => k.name.slice(this.prefix.length)),
+            cursor: res.list_complete ? null : (res.cursor ?? null),
+        };
+    }
+}

package/dist/runtime/migrate.d.ts

@@ -0,0 +1,22 @@
+import type { Driver } from "./driver";
+import type { SchemaDef } from "../sdk/schema";
+export interface MigrationReport {
+    changed: boolean;
+    created: string[];
+    added: string[];
+    /** Tables rebuilt to apply a drop / rename / type change. */
+    rebuilt: string[];
+    /** Tables dropped because the schema no longer declares them. */
+    droppedTables: string[];
+    /** Destructive ops detected but NOT applied because destructive migrations are
+     * disabled (the default). Re-deploy with allowDestructive to apply them. */
+    skipped: string[];
+}
+export interface MigrateOptions {
+    /** Apply destructive changes (drop/rebuild/type-change/table-drop). Off by default
+     * — data-loss is gated behind an explicit opt-in (env `PRAMEN_ALLOW_DESTRUCTIVE`).
+     * Additive changes (create table, add column, add index) always apply. */
+    allowDestructive?: boolean;
+}
+export declare function schemaHash(schema: SchemaDef): string;
+export declare function migrate(driver: Driver, schema: SchemaDef, opts?: MigrateOptions): Promise<MigrationReport>;

package/dist/runtime/migrate.js

@@ -0,0 +1,158 @@
+// Schema migration — applied on boot, wrapped in a transaction by the caller.
+// Runs over a Driver, so it works on any SQLite-flavored substrate (DO SQLite and
+// D1). The introspection (`PRAGMA table_info`, `sqlite_master`) and table-rebuild
+// are SQLite-specific; a Postgres/MySQL migrator would be a separate adapter.
+// Reconciles the live store with the declared schema in two passes:
+//   1. additive (no data loss): missing table -> CREATE TABLE; missing column ->
+//      ALTER TABLE ADD COLUMN (nullable).
+//   2. destructive: a live column the schema no longer declares is DROPPED, a type
+//      change is applied, and a `renamedFrom` column is renamed — all via the
+//      standard SQLite table-rebuild (create new, copy, drop old, rename). This is
+//      auto-applied: a bad deploy CAN lose data, by design (WIP, no backward-compat).
+//
+// A schema hash in the internal `_pramen_meta` table lets an unchanged schema skip
+// introspection entirely on warm boots. The live table (PRAGMA) is the ground
+// truth diffed against the schema — no stored shape needed.
+//
+// ADD COLUMN is always nullable (SQLite can't add NOT NULL to a populated table).
+// A rename can't be inferred from a diff (a removed + added column is ambiguous),
+// so it must be declared with `renamedFrom`; otherwise it is applied as drop+add.
+import { addColumnSql, createTableSql, indexStatements, sqlType } from "./ddl";
+import { digest } from "./digest";
+/** Internal bookkeeping tables the migrator must never touch — pramen's own, SQLite's,
+ * and the substrate's (D1 keeps `_cf_*` / `d1_*` tables in sqlite_master and forbids
+ * dropping them). Matched case-insensitively. */
+function isInternalTable(name) {
+    const n = name.toLowerCase();
+    return (n.startsWith("_pramen") ||
+        n.startsWith("__pramen") ||
+        n.startsWith("sqlite_") ||
+        n.startsWith("_cf_") ||
+        n.startsWith("d1_"));
+}
+function ident(name) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+        throw new Error(`invalid identifier: ${name}`);
+    return name;
+}
+export function schemaHash(schema) {
+    const canon = {};
+    for (const [table, def] of Object.entries(schema))
+        canon[table] = def.fields;
+    return digest(canon);
+}
+/** Live columns of a table -> their declared SQL type (uppercased). Empty if the
+ * table doesn't exist. */
+async function tableColumns(driver, table) {
+    const rows = (await driver.exec(`PRAGMA table_info(${ident(table)})`, []));
+    return new Map(rows.map((r) => [r.name, (r.type || "").toUpperCase()]));
+}
+async function readMeta(driver, key) {
+    const rows = (await driver.exec(`SELECT value FROM _pramen_meta WHERE key = ?`, [key]));
+    return rows[0]?.value;
+}
+async function writeMeta(driver, key, value) {
+    await driver.exec(`INSERT OR REPLACE INTO _pramen_meta (key, value) VALUES (?, ?)`, [key, value]);
+}
+/** Rebuild a table to exactly the declared schema: create a temp table, copy each
+ * desired column from its source (renamed or same-named live column, CAST on a
+ * type change; brand-new columns left NULL), drop the old table, rename the temp. */
+async function rebuildTable(driver, table, def, live) {
+    const tmp = `__pramen_rebuild_${table}`;
+    await driver.exec(`DROP TABLE IF EXISTS ${ident(tmp)}`, []);
+    await driver.exec(createTableSql(tmp, def), []);
+    const destCols = [];
+    const srcExprs = [];
+    for (const [name, field] of Object.entries(def.fields)) {
+        const f = field;
+        const src = f.renamedFrom && live.has(f.renamedFrom) ? f.renamedFrom : live.has(name) ? name : undefined;
+        if (!src)
+            continue; // brand-new column with no source -> leave NULL
+        const target = sqlType(f);
+        destCols.push(ident(name));
+        srcExprs.push(live.get(src) === target ? ident(src) : `CAST(${ident(src)} AS ${target})`);
+    }
+    if (destCols.length > 0) {
+        await driver.exec(`INSERT INTO ${ident(tmp)} (${destCols.join(", ")}) SELECT ${srcExprs.join(", ")} FROM ${ident(table)}`, []);
+    }
+    await driver.exec(`DROP TABLE ${ident(table)}`, []);
+    await driver.exec(`ALTER TABLE ${ident(tmp)} RENAME TO ${ident(table)}`, []);
+}
+export async function migrate(driver, schema, opts = {}) {
+    await driver.exec(`CREATE TABLE IF NOT EXISTS _pramen_meta (key TEXT PRIMARY KEY, value TEXT)`, []);
+    const allowDestructive = opts.allowDestructive ?? false;
+    const current = schemaHash(schema);
+    if ((await readMeta(driver, "schema_hash")) === current)
+        return { changed: false, created: [], added: [], rebuilt: [], droppedTables: [], skipped: [] };
+    const created = [];
+    const added = [];
+    const rebuilt = [];
+    const droppedTables = [];
+    const skipped = [];
+    for (const [table, def] of Object.entries(schema)) {
+        const existing = await tableColumns(driver, table);
+        if (existing.size === 0) {
+            await driver.exec(createTableSql(table, def), []);
+            created.push(table);
+            continue;
+        }
+        // Pass 1 — additive: add any column the schema declares but the table lacks.
+        for (const [name, field] of Object.entries(def.fields)) {
+            if (existing.has(name))
+                continue;
+            await driver.exec(`ALTER TABLE ${ident(table)} ADD COLUMN ${addColumnSql(name, field)}`, []);
+            added.push(`${table}.${name}`);
+        }
+        // Pass 2 — destructive: rebuild if any live column must be dropped, a declared
+        // column changed type, or a rename hint points at an existing live column.
+        const live = await tableColumns(driver, table); // re-read (now includes additively-added columns)
+        const desired = new Set(Object.keys(def.fields));
+        const renamedSources = new Set();
+        for (const f of Object.values(def.fields)) {
+            const from = f.renamedFrom;
+            if (from && live.has(from))
+                renamedSources.add(from);
+        }
+        const needsDrop = [...live.keys()].some((c) => !desired.has(c) && !renamedSources.has(c));
+        const needsTypeChange = Object.entries(def.fields).some(([n, f]) => live.has(n) && live.get(n) !== sqlType(f));
+        if (needsDrop || needsTypeChange || renamedSources.size > 0) {
+            if (allowDestructive) {
+                await rebuildTable(driver, table, def, live);
+                rebuilt.push(table);
+            }
+            else {
+                skipped.push(`rebuild ${table} (drop/type-change/rename)`);
+            }
+        }
+    }
+    // Ensure unique/index declarations (idempotent, via IF NOT EXISTS). Indexes can be
+    // added to an existing table without a rebuild; a stale index from a removed
+    // declaration is left in place (cleanup is future work).
+    for (const [table, def] of Object.entries(schema)) {
+        for (const stmt of indexStatements(table, def))
+            await driver.exec(stmt, []);
+    }
+    // Drop tables the schema no longer declares (internal bookkeeping tables skipped).
+    const liveTables = (await driver.exec(`SELECT name FROM sqlite_master WHERE type = 'table'`, []));
+    for (const { name } of liveTables) {
+        if (isInternalTable(name) || name in schema)
+            continue;
+        if (allowDestructive) {
+            await driver.exec(`DROP TABLE ${ident(name)}`, []);
+            droppedTables.push(name);
+        }
+        else {
+            skipped.push(`drop table ${name}`);
+        }
+    }
+    // Only record the schema as applied when fully reconciled. If destructive changes
+    // were skipped, leave the hash so a later deploy (with allowDestructive) retries —
+    // additive work is idempotent, so re-running is safe.
+    if (skipped.length === 0) {
+        await writeMeta(driver, "schema_hash", current);
+    }
+    else {
+        console.warn(`pramen: ${skipped.length} destructive migration(s) skipped (set PRAMEN_ALLOW_DESTRUCTIVE=true to apply): ${skipped.join("; ")}`);
+    }
+    return { changed: true, created, added, rebuilt, droppedTables, skipped };
+}

package/dist/runtime/protocol.d.ts

@@ -0,0 +1,40 @@
+export interface SubscribeMsg {
+    type: "subscribe";
+    id: string;
+    name: string;
+    input?: unknown;
+}
+export interface UnsubscribeMsg {
+    type: "unsubscribe";
+    id: string;
+}
+export interface CallMsg {
+    type: "call";
+    id: string;
+    name: string;
+    input?: unknown;
+}
+export type ClientMsg = SubscribeMsg | UnsubscribeMsg | CallMsg;
+export type ServerMsg = {
+    type: "data";
+    id: string;
+    result: unknown;
+} | {
+    type: "result";
+    id: string;
+    result: unknown;
+} | {
+    type: "error";
+    id: string;
+    error: string;
+};
+/** A live subscription, persisted on the socket so it survives DO hibernation. */
+export interface Subscription {
+    id: string;
+    name: string;
+    input: unknown;
+    /** Tables the query read — the coarse prefilter for which writes might matter. */
+    tables: string[];
+    /** Digest of the last result pushed — used to suppress no-op (row-level) pushes. */
+    digest: string;
+}

package/dist/runtime/protocol.js

@@ -0,0 +1,12 @@
+// Live-query wire protocol (JSON over WebSocket).
+//
+// Client -> server:
+//   { type: "subscribe",   id, name, input? }   // query handler; initial data + pushes
+//   { type: "unsubscribe", id }
+//   { type: "call",        id, name, input? }    // one-shot any handler (query or mutation)
+//
+// Server -> client:
+//   { type: "data",   id, result }   // initial subscription result + every update
+//   { type: "result", id, result }   // reply to a one-shot call
+//   { type: "error",  id, error }
+export {};

package/dist/runtime/read-engine.d.ts

@@ -0,0 +1,73 @@
+import type { Dialect } from "./driver";
+export type CmpOp = "=" | "!=" | ">" | ">=" | "<" | "<=" | "LIKE";
+export type SqlExpr = {
+    t: "true";
+} | {
+    t: "false";
+} | {
+    t: "cmp";
+    op: CmpOp;
+    col: string;
+    value: unknown;
+} | {
+    t: "in";
+    col: string;
+    values: unknown[];
+    negate: boolean;
+} | {
+    t: "null";
+    col: string;
+    negate: boolean;
+} | {
+    t: "and";
+    parts: SqlExpr[];
+} | {
+    t: "or";
+    parts: SqlExpr[];
+};
+export declare const TRUE: SqlExpr;
+export declare const FALSE: SqlExpr;
+export declare const cmp: (op: CmpOp, col: string, value: unknown) => SqlExpr;
+export declare const isNull: (col: string, negate?: boolean) => SqlExpr;
+export declare const inList: (col: string, values: unknown[], negate?: boolean) => SqlExpr;
+export declare const and: (...parts: SqlExpr[]) => SqlExpr;
+export declare const or: (...parts: SqlExpr[]) => SqlExpr;
+/** Equality (null -> IS NULL). Used by ACL scope building and relation loads. */
+export declare const eq: (col: string, value: unknown) => SqlExpr;
+/** Compile a structured user predicate into a SqlExpr.
+ * Shapes: { col: value } (eq) | { col: { gt, lt, in, like, isNull, … } } | { AND: [...] } | { OR: [...] } */
+export declare function compileWhere(input: Record<string, unknown>): SqlExpr;
+export interface CompiledSql {
+    readonly sql: string;
+    readonly params: unknown[];
+}
+export declare function compileExpr(expr: SqlExpr, dialect: Dialect, params?: unknown[]): CompiledSql;
+/** 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 declare function evalExpr(expr: SqlExpr, row: Record<string, unknown>): boolean;
+export interface OrderBy {
+    column: string;
+    dir?: "asc" | "desc";
+}
+export interface QuerySpec {
+    readonly from: string;
+    readonly where?: SqlExpr;
+    readonly orderBy?: OrderBy[];
+    readonly limit?: number;
+    readonly offset?: number;
+}
+export type AggFn = "count" | "sum" | "avg" | "min" | "max";
+export declare function compileCount(from: string, dialect: Dialect, where?: SqlExpr): CompiledSql;
+export interface Aggregation {
+    fn: AggFn;
+    column?: string;
+}
+export declare function compileAggregate(spec: {
+    from: string;
+    where?: SqlExpr;
+    groupBy?: string[];
+    aggregations: Record<string, Aggregation>;
+}, dialect: Dialect): CompiledSql;
+export declare function compileSelect(spec: QuerySpec, dialect: Dialect): CompiledSql;