@mcp-b/do-runtime 0.1.0

package/dist/src/util/sqlite.d.ts

@@ -0,0 +1,291 @@
+/**
+ * ← workerd `src/workerd/util/sqlite.{h,c++}`
+ *
+ * The SQL backend port. Upstream's seam is the same one: `server.c++` opens
+ * `<actor-id>.<facetId>.sqlite` and hands `ActorSqlite` a `SqliteDatabase`.
+ *
+ * Almost none of upstream's 3,768 lines are ours. `sqlite.{h,c++}` is workerd's
+ * binding to the SQLite C API — statement caching, the VFS, regulators, the
+ * authorizer, the memory-metering allocator. Underneath us that role is played
+ * by `node:sqlite` and sqlite-wasm, which is the storage-backend adaptation the
+ * design record sanctions: `io-gate.h` knows nothing about SQLite, `ActorSqlite`
+ * calls into it, and that seam is upstream's rather than ours.
+ *
+ * So this file is two things stacked:
+ *
+ *  1. `SqlDatabase` / `SqlDatabaseProvider` — the backend seam. `backends/`
+ *     implements it, and nothing above `util/` ever sees a driver type.
+ *  2. `SqliteDatabase` — the small part of upstream's class that is genuinely
+ *     ours, because the layers above call into it and a stateless exec interface
+ *     cannot express it: `onRollback`, the transaction/savepoint stack it needs,
+ *     `reset()` and its `ResetListener` notification, all three of which
+ *     `sqlite-kv.c++` and `sqlite-metadata.c++` reach for; plus `onWrite`,
+ *     `notifyWrite` and `onCriticalError`, which only `io/actor-sqlite.ts`
+ *     reaches for. That last trio lives here rather than one directory up
+ *     because it lives here upstream (`sqlite.h:240`, `:248`, `:267`): a
+ *     callback slot is not actor knowledge, and a reader who finds `onWrite` in
+ *     `sqlite.h` has to find it in this file too. Every consumer takes a
+ *     `SqliteDatabase`, exactly as upstream's take a `SqliteDatabase&`.
+ *
+ * `transactionSync` is NOT here — it lives in `io/actor-sqlite.ts` as
+ * SAVEPOINT/RELEASE with a depth counter, exactly as upstream has it. Today
+ * both browser and Node adapters duplicate `BEGIN IMMEDIATE`, which is why a
+ * nested call is a live SQLite error (§2.4). Moving it inward fixes that.
+ *
+ * Not ported, because the substrate has no equivalent: the `Regulator` /
+ * authorizer machinery (there is no untrusted-SQL path in `util/`, and
+ * `api/sql.ts` owns that question); `SqliteObserver` row-count billing, whose
+ * counters are libsql `STMTSTATUS` extensions neither backend exposes;
+ * `sqlite-metering.{h,c++}`, which swaps SQLite's process-wide allocator to
+ * meter per-database memory — a C-API facility with no JS analogue; and the
+ * point-in-time-recovery APIs, a named substrate boundary in the package README.
+ *
+ * Spec: §1.4, §2.4 in docs/decisions.md.
+ */
+/** The four values SQLite itself accepts after public JSG-style conversion. */
+export type SqlValue = string | number | null | Uint8Array;
+export type SqlResult = {
+    readonly columnNames: readonly string[];
+    readonly rawRows: readonly (readonly unknown[])[];
+    /** Rows changed by this statement, including DML with `RETURNING`. */
+    readonly rowsWritten: number;
+};
+/** ← `SqliteDatabase::IngestResult`. */
+export type SqlIngestResult = {
+    readonly remainder: string;
+    readonly rowsRead: number;
+    readonly rowsWritten: number;
+    readonly statementCount: number;
+};
+/**
+ * One SQLite-compiled statement from the front of a SQL string.
+ *
+ * `sql` is the exact prefix SQLite consumed, including trigger bodies. Keeping
+ * that boundary on the backend is what prevents JavaScript from inventing a
+ * second, subtly different SQL grammar.
+ */
+export interface SqlDatabaseStatement {
+    readonly sql: string;
+    readonly parameterCount: number;
+    execute(params: readonly SqlValue[]): SqlResult;
+    close(): void;
+}
+export declare const SQL_WRONG_BINDINGS_MESSAGE = "Wrong number of parameter bindings for SQL query.";
+/** ← `SQLITE_LIMIT_LENGTH`, raised from 2.2 MB to 4 MiB in workerd 2026-08-20. */
+export declare const SQLITE_LENGTH_LIMIT: number;
+export declare const SQLITE_TOOBIG_MESSAGE = "string or blob too big: SQLITE_TOOBIG";
+/** The part of `sqlite3_limit(SQLITE_LIMIT_LENGTH)` visible at the JS binding seam. */
+export declare function requireSqliteLength(value: unknown): void;
+export declare const SQL_PRELUDE_BINDINGS_MESSAGE: string;
+/**
+ * One open database. Synchronous exec, matching every substrate we have: in a
+ * SQLite-backed Durable Object reads return a value rather than a promise
+ * (§1.4), which is what makes the input gate cheap.
+ */
+export interface SqlDatabase {
+    /** Compile exactly the first statement, using SQLite's own statement boundary. */
+    prepare(sql: string): SqlDatabaseStatement;
+    exec(sql: string, params: readonly SqlValue[]): SqlResult;
+    readonly databaseSize: number;
+    /**
+     * ← `sqlite3_get_autocommit(db) == 0`, which is how upstream's
+     * `handleCriticalError` learns that SQLite rolled a transaction back on its
+     * own (`sqlite.c++:669-691`).
+     *
+     * SQLite auto-rolls-back on `SQLITE_FULL`, `SQLITE_IOERR`, `SQLITE_NOMEM` and
+     * `SQLITE_INTERRUPT`. Nothing announces it, so without this the savepoint
+     * stack above would keep believing a transaction is open and the rollback
+     * callbacks would never fire — a stale cache with nothing thrown, which is
+     * the one failure this layer must never produce.
+     */
+    readonly inTransaction: boolean;
+    /**
+     * ← `SqliteDatabase::reset()` — "delete the underlying database file and
+     * create a new one in its place", which is how upstream implements
+     * `deleteAll()`.
+     *
+     * On the backend rather than above it because only the backend knows how to
+     * recreate its own file, and because the alternative — enumerating and
+     * dropping every table — is the fragile dance today's `storage.ts` performs,
+     * complete with an FTS5 shadow-table ordering hazard its comment documents.
+     * The `SqlDatabase` reference stays valid across the call; what changes is
+     * the file behind it.
+     */
+    reset(): void;
+    close(): void;
+}
+/**
+ * Opens databases within ONE actor's storage scope. The package derives the
+ * names (`"root"`, `` `facet-${facetId}` ``); the host maps them onto files.
+ * OPFS layout knowledge stays with the host — this package never reaches for
+ * `navigator.storage`.
+ */
+export interface SqlDatabaseProvider {
+    open(name: string): Promise<SqlDatabase>;
+}
+/** A portable, host-owned image of every SQLite database in one actor storage scope. */
+export type SqlDatabaseSnapshot = {
+    readonly version: 1;
+    readonly databases: readonly {
+        readonly name: string;
+        readonly image: Uint8Array;
+    }[];
+};
+/** Local backup/restore. This is deliberately not Cloudflare's time-indexed PITR service. */
+export interface SqlDatabaseSnapshotProvider extends SqlDatabaseProvider {
+    /** Close every database opened through this provider before snapshot or placement teardown. */
+    close(): void;
+    exportSnapshot(): Promise<SqlDatabaseSnapshot>;
+    importSnapshot(snapshot: SqlDatabaseSnapshot): Promise<void>;
+}
+export declare function requireSafeDatabaseName(name: string): void;
+/** Validate the complete snapshot before a backend replaces any files. */
+export declare function requireValidSqlDatabaseSnapshot(snapshot: SqlDatabaseSnapshot): void;
+/**
+ * ← `SqliteDatabase::QueryOptions`. The C++ regulator pointer is narrowed to
+ * a callback over the exact SQL source SQLite compiled; `api/sql.ts` owns the
+ * policy because this backend seam owns no public-API knowledge.
+ *
+ * `allowUnconfirmed`'s only destination is `onWrite(bool allowUnconfirmed)`,
+ * which fires *before* the statement executes so the automatic transaction
+ * opens first — see `isWrite` below for how a statement is known to be a write
+ * without the compiled plan upstream reads it from.
+ */
+export type QueryOptions = {
+    allowUnconfirmed?: boolean;
+    /** The public SQL regulator, run once against each SQLite-compiled statement. */
+    regulate?: (sql: string) => void;
+};
+/**
+ * ← the state `SqliteDatabase::onCriticalError` reports and
+ * `observedCriticalError()` latches.
+ *
+ * Raised when SQLite has rolled back an open transaction on its own. Upstream
+ * hands this to `ActorSqlite`, which treats it as fatal; §1.6 is why — a
+ * storage failure this severe destroys the object rather than being survived.
+ * Until `io/actor-sqlite.ts` wires it to `onBroken`, latching it and refusing
+ * every subsequent statement is what keeps a caller from reading through a
+ * cache that is knowingly wrong.
+ */
+export declare class SqliteCriticalError extends Error {
+    readonly name = "SqliteCriticalError";
+}
+/**
+ * ← `SqliteDatabase::ResetListener`.
+ *
+ * Upstream's is a base class whose constructor registers and whose destructor
+ * unregisters. JS has neither, so registration is the explicit
+ * `db.addResetListener(this)` call — the same translation Section 1 applied to
+ * every kj destructor.
+ */
+export interface ResetListener {
+    /** Called before the database is actually reset. */
+    beforeSqliteReset(): void;
+}
+/** ← `SqliteDatabase::Query::isNull(uint column)`. */
+export declare function isNull(row: readonly unknown[], column: number): boolean;
+/** ← `SqliteDatabase::Query::getBlob(uint column)`. Fails closed on any other column type. */
+export declare function getBlob(row: readonly unknown[], column: number): Uint8Array;
+/** ← `SqliteDatabase::Query::getText(uint column)`. Fails closed on any other column type. */
+export declare function getText(row: readonly unknown[], column: number): string;
+/**
+ * ← `SqliteDatabase::Query::getInt64(uint column)`.
+ *
+ * Narrowed to a safe integer rather than upstream's `int64_t`: a JS number
+ * cannot carry the full range, and a silently-rounded row id or alarm time is
+ * exactly the kind of corruption this layer must not produce.
+ */
+export declare function getInt64(row: readonly unknown[], column: number): number;
+/**
+ * ← `SqliteDatabase`, restricted to the members `sqlite-kv` and
+ * `sqlite-metadata` actually call.
+ *
+ * The one piece of real machinery here is the transaction/savepoint stack that
+ * `onRollback()` needs. Upstream learns of a `BEGIN` / `SAVEPOINT` / `COMMIT` /
+ * `RELEASE` / `ROLLBACK` from the SQLite authorizer while the statement is
+ * being compiled (`prepareSql` fills a `ParseContext::stateChange`); we have no
+ * authorizer, so the statement text is the only source. `applyChange` below is
+ * a line-for-line port of upstream's; only where the `StateChange` comes from
+ * differs.
+ */
+export declare class SqliteDatabase {
+    #private;
+    constructor(backend: SqlDatabase);
+    /**
+     * Invokes the given callback whenever a query begins which may write to the
+     * database. The callback is called just before executing the query.
+     *
+     * Durable Objects uses this to automatically begin a transaction and close the
+     * output gate.
+     *
+     * Note that the write callback is NOT called before (or at any point during) a
+     * `reset()`. Use the `ResetListener` mechanism for that case.
+     */
+    onWrite(callback: (allowUnconfirmed: boolean) => void): void;
+    /**
+     * Invokes the given callback when a "critical error" causes an automatic
+     * rollback during a transaction.
+     *
+     * See: https://www.sqlite.org/lang_transaction.html#response_to_errors_within_a_transaction
+     *
+     * Upstream passes `(errorMessage, maybeException)` and lets the caller build
+     * the exception; `#checkForAutoRollback` has already built one by the time it
+     * can tell a rollback happened, so the callback receives that.
+     */
+    onCriticalError(callback: (exception: SqliteCriticalError) => void): void;
+    /**
+     * Invoke the onWrite() callback.
+     *
+     * "This is useful when the caller is about to execute a statement which SQLite
+     * considers read-only, but needs to be considered a write for our purposes. In
+     * particular, we use the onWrite callback to start automatic transactions, and
+     * we use the SAVEPOINT statement to implement explicit transactions. For
+     * synchronous transactions, the explicit transaction needs to be nested inside
+     * the automatic transaction, so we need to force an auto-transaction to start
+     * before the SAVEPOINT."
+     */
+    notifyWrite(allowUnconfirmed?: boolean): void;
+    /** ← `SqliteDatabase::run`, in both its bare and its `QueryOptions` form. */
+    run(sql: string, ...bindings: SqlValue[]): SqlResult;
+    run(options: QueryOptions, sql: string, ...bindings: SqlValue[]): SqlResult;
+    /** ← `SqliteDatabase::ingestSql`: execute complete statements, retain the partial tail. */
+    ingest(sql: string, regulate?: (sql: string) => void): SqlIngestResult;
+    /**
+     * ← `SqliteDatabase::observedCriticalError()`. The named state
+     * `io/actor-sqlite.ts` wires to `onBroken`, so it does not have to re-derive
+     * the condition from an exception it caught.
+     */
+    observedCriticalError(): SqliteCriticalError | undefined;
+    /**
+     * The guard for any read this package serves from a cache rather than from a
+     * statement. Those are the only paths a latched critical error would not
+     * already stop, and they are exactly the paths whose answer is wrong once
+     * SQLite has rolled back underneath them.
+     */
+    assertUsable(): void;
+    get databaseSize(): number;
+    /**
+     * ← `SqliteDatabase::onRollback`.
+     *
+     * "Register a callback which shall be called if the current transaction is
+     * rolled back. If the current transaction commits, then the callback is
+     * discarded without invoking it. [...] When a rollback occurs, callbacks are
+     * invoked in the reverse of the order in which they were registered."
+     *
+     * With nothing open there is nothing that can roll back, so the callback is
+     * dropped — upstream's `if (inTransaction || !savepoints.empty())`.
+     */
+    onRollback(callback: () => void): void;
+    addResetListener(listener: ResetListener): void;
+    removeResetListener(listener: ResetListener): void;
+    /** ← `SqliteDatabase::reset()`. */
+    reset(): void;
+    close(): void;
+}
+type SqliteSchemaDatabase = Pick<SqlDatabase, "exec"> | Pick<SqliteDatabase, "run">;
+/**
+ * Returns whether a runtime-owned table exists, and refuses any present shape
+ * other than the one this release writes.
+ */
+export declare function hasCurrentSqliteTable(db: SqliteSchemaDatabase, name: string, createSql: string): boolean;
+export {};

package/package.json

@@ -0,0 +1,111 @@
+{
+  "name": "@mcp-b/do-runtime",
+  "version": "0.1.0",
+  "description": "Cloudflare's Durable Object runtime (workerd), ported to TypeScript: actors with input/output gates, SQLite storage, facets and alarms, running in the browser and in Node.",
+  "keywords": [
+    "actors",
+    "browser",
+    "cloudflare",
+    "durable-objects",
+    "opfs",
+    "sqlite",
+    "typescript",
+    "workerd"
+  ],
+  "homepage": "https://github.com/WebMCP-org/do-runtime#readme",
+  "bugs": {
+    "url": "https://github.com/WebMCP-org/do-runtime/issues"
+  },
+  "license": "FSL-1.1-MIT",
+  "author": "Kukumis, Inc.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WebMCP-org/do-runtime.git"
+  },
+  "type": "module",
+  "types": "./dist/src/index.d.ts",
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "LICENSE",
+    "LICENSE.workerd",
+    "NOTICE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server/alarm-scheduler": {
+      "types": "./dist/src/server/alarm-scheduler.d.ts",
+      "import": "./dist/server/alarm-scheduler.js"
+    },
+    "./backends/sqlite-wasm": {
+      "types": "./dist/backends/sqlite-wasm.d.ts",
+      "import": "./dist/backends/sqlite-wasm.js"
+    },
+    "./backends/node-sqlite": {
+      "types": "./dist/backends/node-sqlite.d.ts",
+      "import": "./dist/backends/node-sqlite.js"
+    },
+    "./cloudflare-workers": {
+      "types": "./dist/src/api/cloudflare-workers.d.ts",
+      "import": "./dist/cloudflare-workers.js"
+    },
+    "./conformance": {
+      "types": "./dist/conformance/host.d.ts",
+      "import": "./dist/conformance.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@ungap/structured-clone": "1.3.3",
+    "capnweb": "0.10.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@changesets/cli": "^2.29.8",
+    "@cloudflare/vitest-pool-workers": "^0.18.8",
+    "@cloudflare/workers-types": "5.20260820.1",
+    "@sqlite.org/sqlite-wasm": "3.53.0-build1",
+    "@types/node": "^26.1.2",
+    "@types/ungap__structured-clone": "1.2.0",
+    "@vitest/browser-playwright": "4.1.10",
+    "playwright": "1.61.1",
+    "publint": "0.3.23",
+    "typescript": "^5.9.3",
+    "vite": "^8.1.5",
+    "vitest": "4.1.10",
+    "workerd": "1.20260820.1",
+    "wrangler": "^4.114.0"
+  },
+  "engines": {
+    "node": ">=24.11.0"
+  },
+  "scripts": {
+    "build": "pnpm build:package",
+    "typecheck": "pnpm build:package && tsc -b tsconfig.json && tsc -p conformance/tsconfig.json && tsc -p examples/extension/tsconfig.page.json && tsc -p examples/extension/tsconfig.worker.json && tsc -p examples/vibe-platform/tsconfig.page.json && tsc -p examples/vibe-platform/tsconfig.worker.json",
+    "test": "pnpm test:unit && pnpm test:conformance",
+    "examples:build": "pnpm build:package && pnpm --filter \"do-runtime-example-*\" build",
+    "test:examples": "pnpm build:package && node examples/extension/scripts/e2e.mjs && node examples/vibe-platform/scripts/e2e.mjs",
+    "test:unit": "vitest run --config vitest.unit.config.ts",
+    "test:conformance": "pnpm test:conformance-workerd && pnpm test:conformance-node && pnpm test:conformance-browser",
+    "test:conformance-workerd": "vitest run --config conformance/workerd/vitest.config.ts",
+    "test:conformance-node": "vitest run --config conformance/node/vitest.config.ts",
+    "test:conformance-browser": "vitest run --config conformance/browser/vitest.config.ts",
+    "check:oracle": "node scripts/check-workerd-oracle.mjs",
+    "check:package": "pnpm build:package && publint && attw --pack . --profile esm-only && node scripts/check-package.mjs",
+    "build:package": "node scripts/build-package.mjs && tsc -p tsconfig.publish.json && node scripts/fix-declaration-imports.mjs",
+    "changeset": "changeset",
+    "changeset:version": "changeset version",
+    "changeset:publish": "pnpm check:package && changeset publish",
+    "publish:dry": "pnpm publish --access public --dry-run",
+    "bench:node": "vitest run --config conformance/bench/vitest.node.config.ts",
+    "bench:browser": "vitest run --config conformance/bench/vitest.browser.config.ts"
+  }
+}