feat: US-018 - Tighten runtime SQL boundary types

Author: NathanFlurry

rivetkit-typescript/CLAUDE.md

@@ -16,6 +16,7 @@
 
 - Select runtime behavior from `CoreRuntime.kind`, not `instanceof` adapter classes; NAPI maps to the native runtime kind and wasm maps to wasm.
 - Keep `CoreRuntime` SQL methods on the portable `RuntimeSql*` structs from `packages/rivetkit/src/registry/runtime.ts`; NAPI-only `Buffer` conversion belongs inside `NapiCoreRuntime`.
+- Keep `RuntimeSqlBindParam` variants exact and `RuntimeSqlExecuteResult.route` limited to `read`, `write`, or `writeFallback`; normalize generated adapter output before returning it.
 - Keep `CoreRuntime` byte payloads on `RuntimeBytes`/`Uint8Array`; NAPI-only `Buffer` conversion belongs inside `NapiCoreRuntime`.
 - Shared actor glue in `packages/rivetkit/src/registry/native.ts` should construct `RuntimeBytes`/`Uint8Array`; leave `Buffer` creation to `NapiCoreRuntime`.
 - Wasm bindings for NAPI-supported runtime APIs should forward to `rivetkit-core`; avoid placeholder returns that break runtime parity.

rivetkit-typescript/packages/rivetkit/src/common/database/native-database.test.ts

@@ -147,18 +147,15 @@ describe("wrapJsNativeDatabase", () => {
 			blob,
 		]);
 
-		expect(native.executeCalls[0]?.params).toMatchObject([
+		expect(native.executeCalls[0]?.params).toEqual([
 			{ kind: "int", intValue: 1 },
 			{ kind: "int", intValue: 1 },
 			{ kind: "text", textValue: "text" },
 			{ kind: "float", floatValue: 1.5 },
 			{ kind: "null" },
 			{ kind: "null" },
-			{ kind: "blob" },
+			{ kind: "blob", blobValue: Buffer.from(blob) },
 		]);
-		const blobParam = native.executeCalls[0]?.params?.[6];
-		expect(blobParam?.blobValue).toBeInstanceOf(Uint8Array);
-		expect(Array.from(blobParam?.blobValue ?? [])).toEqual([1, 2, 3]);
 
 		native.resolveNext({ columns: ["value"], rows: [[1]] });
 
@@ -168,6 +165,30 @@ describe("wrapJsNativeDatabase", () => {
 		});
 	});
 
+	test("normalizes native execute routes and rejects unsupported routes", async () => {
+		const native = new FakeNativeDatabase();
+		const db = wrapJsNativeDatabase(native);
+
+		const read = db.execute("SELECT 1");
+		native.resolveNext({ route: "read" });
+		await expect(read).resolves.toMatchObject({ route: "read" });
+
+		const write = db.execute("INSERT INTO test VALUES (1)");
+		native.resolveNext({ route: "write" });
+		await expect(write).resolves.toMatchObject({ route: "write" });
+
+		const fallback = db.execute("SELECT last_insert_rowid()");
+		await expect(fallback).resolves.toMatchObject({
+			route: "writeFallback",
+		});
+
+		const unsupported = db.execute("SELECT 2");
+		native.resolveNext({ route: "custom" });
+		await expect(unsupported).rejects.toThrow(
+			"unsupported sqlite execute route: custom",
+		);
+	});
+
 	test("close waits for admitted native calls and rejects new work", async () => {
 		const native = new FakeNativeDatabase();
 		const db = wrapJsNativeDatabase(native);

rivetkit-typescript/packages/rivetkit/src/common/database/native-database.ts

@@ -5,13 +5,43 @@ import type {
 	SqliteExecuteResult,
 } from "./config";
 
-interface NativeBindParam {
-	kind: "null" | "int" | "float" | "text" | "blob";
-	intValue?: number;
-	floatValue?: number;
-	textValue?: string;
-	blobValue?: Buffer;
-}
+type NativeBindNoValues = {
+	intValue?: never;
+	floatValue?: never;
+	textValue?: never;
+	blobValue?: never;
+};
+
+type NativeBindParam =
+	| ({ kind: "null" } & NativeBindNoValues)
+	| {
+			kind: "int";
+			intValue: number;
+			floatValue?: never;
+			textValue?: never;
+			blobValue?: never;
+	  }
+	| {
+			kind: "float";
+			intValue?: never;
+			floatValue: number;
+			textValue?: never;
+			blobValue?: never;
+	  }
+	| {
+			kind: "text";
+			intValue?: never;
+			floatValue?: never;
+			textValue: string;
+			blobValue?: never;
+	  }
+	| {
+			kind: "blob";
+			intValue?: never;
+			floatValue?: never;
+			textValue?: never;
+			blobValue: Buffer;
+	  };
 
 interface NativeExecResult {
 	columns: string[];

rivetkit-typescript/packages/rivetkit/src/registry/napi-runtime.ts

@@ -38,6 +38,7 @@ import type {
 	RuntimeWebSocketEvent,
 	WebSocketHandle,
 } from "./runtime";
+import { normalizeRuntimeSqlExecuteResult } from "./runtime";
 
 type NativeBindings = typeof import("@rivetkit/rivetkit-napi");
 type NapiSqlDatabase = ReturnType<NativeActorContext["sql"]>;
@@ -80,13 +81,18 @@ function asActorFactoryHandle(handle: NativeActorFactory): ActorFactoryHandle {
 function toNapiSqlBindParam(
 	param: RuntimeSqlBindParam,
 ): NonNullable<NapiSqlBindParams>[number] {
-	return {
-		kind: param.kind,
-		intValue: param.intValue,
-		floatValue: param.floatValue,
-		textValue: param.textValue,
-		blobValue: param.blobValue ? Buffer.from(param.blobValue) : undefined,
-	};
+	switch (param.kind) {
+		case "null":
+			return { kind: "null" };
+		case "int":
+			return { kind: "int", intValue: param.intValue };
+		case "float":
+			return { kind: "float", floatValue: param.floatValue };
+		case "text":
+			return { kind: "text", textValue: param.textValue };
+		case "blob":
+			return { kind: "blob", blobValue: Buffer.from(param.blobValue) };
+	}
 }
 
 function toNapiSqlBindParams(params?: RuntimeSqlBindParams): NapiSqlBindParams {
@@ -521,21 +527,23 @@ export class NapiCoreRuntime implements CoreRuntime {
 		sql: string,
 		params?: RuntimeSqlBindParams,
 	): Promise<RuntimeSqlExecuteResult> {
-		return await this.#actorSql(ctx).execute(
+		const result = await this.#actorSql(ctx).execute(
 			sql,
 			toNapiSqlBindParams(params),
 		);
+		return normalizeRuntimeSqlExecuteResult(result);
 	}
 
 	async actorSqlExecuteWrite(
 		ctx: ActorContextHandle,
 		sql: string,
 		params?: RuntimeSqlBindParams,
 	): Promise<RuntimeSqlExecuteResult> {
-		return await this.#actorSql(ctx).executeWrite(
+		const result = await this.#actorSql(ctx).executeWrite(
 			sql,
 			toNapiSqlBindParams(params),
 		);
+		return normalizeRuntimeSqlExecuteResult(result);
 	}
 
 	async actorSqlQuery(

rivetkit-typescript/packages/rivetkit/src/registry/runtime.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "vitest";
+import {
+	normalizeRuntimeSqlExecuteResult,
+	type RuntimeSqlBindParam,
+	type RuntimeSqlBindParams,
+	type RuntimeSqlExecuteResult,
+} from "./runtime";
+
+describe("runtime SQL boundary", () => {
+	test("accepts exact bind param variants", () => {
+		const blob = new Uint8Array([1, 2, 3]);
+		const params = [
+			{ kind: "null" },
+			{ kind: "int", intValue: 1 },
+			{ kind: "float", floatValue: 1.5 },
+			{ kind: "text", textValue: "text" },
+			{ kind: "blob", blobValue: blob },
+		] satisfies RuntimeSqlBindParams;
+
+		expect(params).toEqual([
+			{ kind: "null" },
+			{ kind: "int", intValue: 1 },
+			{ kind: "float", floatValue: 1.5 },
+			{ kind: "text", textValue: "text" },
+			{ kind: "blob", blobValue: blob },
+		]);
+	});
+
+	test("rejects bind params with mismatched value fields at typecheck time", () => {
+		const invalidIntParamCandidate = {
+			kind: "int",
+			intValue: 1,
+			textValue: "extra",
+		} as const;
+		// @ts-expect-error Runtime SQL int params must only carry intValue.
+		const invalidIntParam: RuntimeSqlBindParam = invalidIntParamCandidate;
+
+		expect(invalidIntParam.kind).toBe("int");
+	});
+
+	test("normalizes exact execute result routes", () => {
+		const base = {
+			columns: ["value"],
+			rows: [[1]],
+			changes: 1,
+			lastInsertRowId: null,
+		};
+
+		expect(
+			normalizeRuntimeSqlExecuteResult({ ...base, route: "read" }).route,
+		).toBe("read");
+		expect(
+			normalizeRuntimeSqlExecuteResult({ ...base, route: "write" }).route,
+		).toBe("write");
+		expect(
+			normalizeRuntimeSqlExecuteResult({
+				...base,
+				route: "writeFallback",
+			}).route,
+		).toBe("writeFallback");
+		expect(() =>
+			normalizeRuntimeSqlExecuteResult({ ...base, route: "custom" }),
+		).toThrow("unsupported runtime sqlite execute route: custom");
+	});
+
+	test("rejects custom execute result routes at typecheck time", () => {
+		const invalidRouteResultCandidate = {
+			columns: [],
+			rows: [],
+			changes: 0,
+			route: "custom",
+		} as const;
+		// @ts-expect-error Runtime SQL execute routes are exact.
+		const invalidRouteResult: RuntimeSqlExecuteResult =
+			invalidRouteResultCandidate;
+
+		expect(invalidRouteResult.route).toBe("custom");
+	});
+});

rivetkit-typescript/packages/rivetkit/src/registry/runtime.ts

@@ -109,13 +109,43 @@ export interface RuntimeKvEntry {
 	value: RuntimeBytes;
 }
 
-export interface RuntimeSqlBindParam {
-	kind: "null" | "int" | "float" | "text" | "blob";
-	intValue?: number;
-	floatValue?: number;
-	textValue?: string;
-	blobValue?: Uint8Array;
-}
+type RuntimeSqlBindNoValues = {
+	intValue?: never;
+	floatValue?: never;
+	textValue?: never;
+	blobValue?: never;
+};
+
+export type RuntimeSqlBindParam =
+	| ({ kind: "null" } & RuntimeSqlBindNoValues)
+	| {
+			kind: "int";
+			intValue: number;
+			floatValue?: never;
+			textValue?: never;
+			blobValue?: never;
+	  }
+	| {
+			kind: "float";
+			intValue?: never;
+			floatValue: number;
+			textValue?: never;
+			blobValue?: never;
+	  }
+	| {
+			kind: "text";
+			intValue?: never;
+			floatValue?: never;
+			textValue: string;
+			blobValue?: never;
+	  }
+	| {
+			kind: "blob";
+			intValue?: never;
+			floatValue?: never;
+			textValue?: never;
+			blobValue: RuntimeBytes;
+	  };
 
 export type RuntimeSqlBindParams = RuntimeSqlBindParam[] | null;
 
@@ -126,10 +156,34 @@ export interface RuntimeSqlQueryResult {
 
 export type RuntimeSqlExecResult = RuntimeSqlQueryResult;
 
+export type RuntimeSqlExecuteRoute = "read" | "write" | "writeFallback";
+
 export interface RuntimeSqlExecuteResult extends RuntimeSqlQueryResult {
 	changes: number;
 	lastInsertRowId?: number | null;
-	route: string;
+	route: RuntimeSqlExecuteRoute;
+}
+
+export function normalizeRuntimeSqlExecuteRoute(
+	route: string,
+): RuntimeSqlExecuteRoute {
+	if (route === "read" || route === "write" || route === "writeFallback") {
+		return route;
+	}
+	throw new Error(`unsupported runtime sqlite execute route: ${route}`);
+}
+
+export function normalizeRuntimeSqlExecuteResult(
+	result: RuntimeSqlQueryResult & {
+		changes: number;
+		lastInsertRowId?: number | null;
+		route: string;
+	},
+): RuntimeSqlExecuteResult {
+	return {
+		...result,
+		route: normalizeRuntimeSqlExecuteRoute(result.route),
+	};
 }
 
 export interface RuntimeSqlRunResult {

rivetkit-typescript/packages/rivetkit/src/registry/wasm-runtime.ts

@@ -51,6 +51,7 @@ import type {
 	RuntimeWebSocketEvent,
 	WebSocketHandle,
 } from "./runtime";
+import { normalizeRuntimeSqlExecuteResult } from "./runtime";
 
 type WasmBindings = WasmRuntimeBindings;
 export type WasmInitInput = WasmRuntimeInitInput;
@@ -736,17 +737,21 @@ export class WasmCoreRuntime implements CoreRuntime {
 		sql: string,
 		params?: RuntimeSqlBindParams,
 	): Promise<RuntimeSqlExecuteResult> {
-		return await callWasm(() => this.#actorSql(ctx).execute(sql, params));
+		const result = await callWasm(() =>
+			this.#actorSql(ctx).execute(sql, params),
+		);
+		return normalizeRuntimeSqlExecuteResult(result);
 	}
 
 	async actorSqlExecuteWrite(
 		ctx: ActorContextHandle,
 		sql: string,
 		params?: RuntimeSqlBindParams,
 	): Promise<RuntimeSqlExecuteResult> {
-		return await callWasm(() =>
+		const result = await callWasm(() =>
 			this.#actorSql(ctx).executeWrite(sql, params),
 		);
+		return normalizeRuntimeSqlExecuteResult(result);
 	}
 
 	async actorSqlQuery(

scripts/ralph/prd.json

@@ -312,7 +312,7 @@
         "Tests pass"
       ],
       "priority": 18,
-      "passes": false,
+      "passes": true,
       "notes": ""
     },
     {