@yydb/yyds 0.0.0 → 0.0.2

package/bin/yyds.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+import { loadYydsNative } from "../src/node/load.ts";
+import { parseStartOptions, runNodeStart } from "../src/node/runtime.ts";
+
+function usage() {
+    return "usage: yyds <init|start|status|stop> --data-dir DIR [--cluster-id ID --node-id ID] [--redis-port PORT] [--pgsql-port PORT] [--mysql-port PORT] [--wire-port PORT]";
+}
+
+function parseCommonArgs(command, args) {
+    const options = { dataDir: "", clusterId: "", nodeId: "", redisPort: 6379, pgsqlPort: undefined, mysqlPort: undefined, wirePort: undefined };
+    for (let index = 0; index < args.length; index += 1) {
+        const flag = args[index];
+        const value = args[index + 1];
+        if (!value || value.startsWith("--")) throw new Error(`missing value for ${flag}`);
+        switch (flag) {
+            case "--data-dir":
+                options.dataDir = value;
+                index += 1;
+                break;
+            case "--cluster-id":
+                options.clusterId = value;
+                index += 1;
+                break;
+            case "--node-id":
+                options.nodeId = value;
+                index += 1;
+                break;
+            case "--redis-port":
+                if (command !== "start") throw new Error(`option ${flag} is not valid for this command`);
+                options.redisPort = Number(value);
+                index += 1;
+                break;
+            case "--pgsql-port":
+                if (command !== "start") throw new Error(`option ${flag} is not valid for this command`);
+                options.pgsqlPort = Number(value);
+                index += 1;
+                break;
+            case "--mysql-port":
+                if (command !== "start") throw new Error(`option ${flag} is not valid for this command`);
+                options.mysqlPort = Number(value);
+                index += 1;
+                break;
+            case "--wire-port":
+                if (command !== "start") throw new Error(`option ${flag} is not valid for this command`);
+                options.wirePort = Number(value);
+                index += 1;
+                break;
+            default:
+                throw new Error(`unknown option '${flag}'\n${usage()}`);
+        }
+    }
+    if (!options.dataDir) throw new Error(usage());
+    if ((command === "init" || command === "start") && (!options.clusterId || !options.nodeId)) {
+        throw new Error(usage());
+    }
+    return options;
+}
+
+async function main(args) {
+    const command = args[0];
+    const rest = args.slice(1);
+    const native = loadYydsNative();
+    const options = parseCommonArgs(command, rest);
+
+    switch (command) {
+        case "init": {
+            const identity = new native.NodeIdentityHandle(options.clusterId, options.nodeId);
+            native.nodeInit(options.dataDir, identity);
+            console.log(`initialized ${options.dataDir}`);
+            return;
+        }
+        case "start":
+            await runNodeStart({
+                dataDir: options.dataDir,
+                clusterId: options.clusterId,
+                nodeId: options.nodeId,
+                redisPort: options.redisPort,
+                pgsqlPort: options.pgsqlPort,
+                mysqlPort: options.mysqlPort,
+                wirePort: options.wirePort,
+            });
+            return;
+        case "status": {
+            const snapshot = native.nodeInspect(options.dataDir);
+            console.log(JSON.stringify({
+                directory: snapshot.directory,
+                identity: JSON.parse(snapshot.identity),
+                ownership: snapshot.ownership,
+                runtime: snapshot.runtime ? JSON.parse(snapshot.runtime) : null,
+                health: snapshot.health,
+            }));
+            return;
+        }
+        case "stop": {
+            const snapshot = native.nodeInspect(options.dataDir);
+            if (snapshot.ownership === "available") throw new Error("node is not running");
+            const runtime = snapshot.runtime ? JSON.parse(snapshot.runtime) : null;
+            if (!runtime) throw new Error("node owner has not published runtime status");
+            native.nodeRequestStop(options.dataDir, runtime.generation);
+            native.nodeWaitUntilStopped(options.dataDir, runtime.generation, 10_000);
+            console.log("stopped");
+            return;
+        }
+        default:
+            throw new Error(command ? `unknown command '${command}'` : usage());
+    }
+}
+
+try {
+    await main(process.argv.slice(2));
+} catch (error) {
+    console.error(`yyds: ${error.message}`);
+    process.exitCode = 1;
+}

package/package.json

@@ -1,63 +1,72 @@
 {
-  "bugs": {
-    "url": "https://github.com/yy-database/yyds/issues"
-  },
-  "description": "YYDS scripting runtime for TypeScript and Node.js",
-  "devDependencies": {
-    "@types/node": "^22.15.0",
-    "typescript": "^5.9.2"
-  },
-  "engines": {
-    "node": ">=18"
-  },
+  "name": "@yydb/yyds",
+  "version": "0.0.2",
+  "description": "Node.js facade, CLI, and native bindings for local YYDS nodes.",
+  "license": "MPL-2.0",
+  "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
-      "default": "./src/node/unsupported.ts",
+      "types": "./src/node/index.ts",
       "node": "./src/node/index.ts",
-      "types": "./src/node/index.ts"
+      "default": "./src/node/unsupported.ts"
     },
     "./node": {
-      "default": "./src/node/unsupported.ts",
+      "types": "./src/node/index.ts",
       "node": "./src/node/index.ts",
-      "types": "./src/node/index.ts"
+      "default": "./src/node/unsupported.ts"
     },
     "./node/cluster": {
-      "default": "./src/node/unsupported.ts",
+      "types": "./src/node/cluster.ts",
       "node": "./src/node/cluster.ts",
-      "types": "./src/node/cluster.ts"
+      "default": "./src/node/unsupported.ts"
+    },
+    "./node/runtime": {
+      "types": "./src/node/runtime.ts",
+      "node": "./src/node/runtime.ts",
+      "default": "./src/node/unsupported.ts"
     }
   },
+  "bin": {
+    "yyds": "./bin/yyds.mjs"
+  },
   "files": [
+    "bin",
     "src"
   ],
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node --experimental-strip-types --test \"./tests/**/*.test.ts\""
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yy-database/yyds.git",
+    "directory": "projects/packages/yyds"
+  },
   "homepage": "https://github.com/yy-database/yyds/tree/dev/projects/packages/yyds#readme",
+  "bugs": {
+    "url": "https://github.com/yy-database/yyds/issues"
+  },
   "keywords": [
     "yyds",
     "scripting",
     "typescript",
     "napi"
   ],
-  "license": "MPL-2.0",
-  "name": "@yydb/yyds",
-  "optionalDependencies": {
-    "@yydb/yyds-darwin-arm64": "0.0.0",
-    "@yydb/yyds-darwin-x64": "0.0.0",
-    "@yydb/yyds-linux-x64": "0.0.0",
-    "@yydb/yyds-win32-x64": "0.0.0"
-  },
   "publishConfig": {
     "access": "public"
   },
-  "repository": {
-    "directory": "projects/packages/yyds",
-    "type": "git",
-    "url": "git+https://github.com/yy-database/yyds.git"
+  "optionalDependencies": {
+    "@yydb/yyds-win32-x64": "0.0.2",
+    "@yydb/yyds-linux-x64": "0.0.2",
+    "@yydb/yyds-darwin-x64": "0.0.2",
+    "@yydb/yyds-darwin-arm64": "0.0.2"
   },
-  "scripts": {
-    "test": "node --experimental-strip-types --test \"./tests/**/*.test.ts\"",
-    "typecheck": "tsc --noEmit -p tsconfig.json"
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.9.2"
   },
-  "sideEffects": false,
-  "type": "module",
-  "version": "0.0.0"
+  "engines": {
+    "node": ">=18"
+  }
 }

package/readme.md

@@ -1,13 +1,39 @@
-# @yyds/yyds
-
-TypeScript facade for the YYDS scripting runtime.
-
-- Browser / Worker: default export (`@yyds/yyds`) or `@yyds/yyds/wasm`
-- Node.js: `@yyds/yyds/node`
-
-Build native and WASM artifacts from the repo root:
-
-```bash
-pnpm build:napi
-pnpm build:wasm
-```
+# @yydb/yyds
+
+Node.js facade for running a local YYDS node: native lifecycle blocks, a small CLI, and helpers used by disguise server entrypoints.
+
+## Exports
+
+| Subpath | Use |
+|---------|-----|
+| `@yydb/yyds` / `@yydb/yyds/node` | Load native bindings, start or inspect a node |
+| `@yydb/yyds/node/cluster` | `launchYydsServer` for `redis-server`, `mysqld`, `postgres` |
+| `@yydb/yyds/node/runtime` | `runNodeStart`, `parseStartOptions` |
+
+The `yyds` binary provides `init`, `start`, `status`, and `stop`. Native addons for your platform are pulled in automatically as optional dependencies.
+
+## Example
+
+```ts
+import { runNodeStart } from "@yydb/yyds/node/runtime";
+
+await runNodeStart({
+  dataDir: "./node-data",
+  clusterId: "local",
+  nodeId: "node-1",
+  redisPort: 6379,
+});
+```
+
+```bash
+yyds init --data-dir ./node-data --cluster-id local --node-id node-1
+yyds start --data-dir ./node-data --cluster-id local --node-id node-1
+yyds status --data-dir ./node-data
+yyds stop --data-dir ./node-data
+```
+
+## Related packages
+
+- [`@yydb/redis`](https://github.com/yy-database/yyds/tree/dev/projects/packages/redis) — Redis protocol disguise
+- [`@yydb/mysql`](https://github.com/yy-database/yyds/tree/dev/projects/packages/mysql) — MySQL protocol disguise
+- [`@yydb/postgresql`](https://github.com/yy-database/yyds/tree/dev/projects/packages/postgresql) — PostgreSQL protocol disguise

package/src/bindings.ts

@@ -1,5 +1,41 @@
-/** Shared Node and WASM binding surface for `@yydb/yyds`. */
-export interface YydsBindings {
-    yydsVersion(): string;
-    ping(): string;
-}
+/** Shared Node and WASM binding surface for `@yydb/yyds`. */
+export interface YydsBindings {
+    yydsVersion(): string;
+    ping(): string;
+    NodeIdentityHandle: new (clusterId: string, nodeId: string) => unknown;
+    NodeLeaseHandle: {
+        acquire(dataDir: string, identity: unknown): unknown;
+    };
+    LocalExecutorHandle: new (dataDir: string) => unknown;
+    RedisServiceHandle: new (lease: unknown, port: number, executor: unknown) => RedisServiceBinding;
+    PgsqlServiceHandle: new (lease: unknown, port: number) => PgsqlServiceBinding;
+    MysqlServiceHandle: new (lease: unknown, port: number) => MysqlServiceBinding;
+    WireServerHandle: new (port: number, executor: unknown) => WireServiceBinding;
+    nodeInit(dataDir: string, identity: unknown): void;
+    nodeInspect(dataDir: string): NodeStatusBinding;
+    nodeReadRuntimeStatus(dataDir: string): string | null;
+    nodeWriteRuntimeStatus(dataDir: string, statusJson: string): void;
+    nodeRequestStop(dataDir: string, generation: string): void;
+    nodeWaitUntilStopped(dataDir: string, generation: string, timeoutMs: number): void;
+    nodeStopRequested(dataDir: string, generation: string): boolean;
+    nodeClearRuntimeArtifacts(dataDir: string, generation: string): void;
+}
+
+export interface ServiceBinding {
+    address(): string;
+    isFinished(): boolean;
+    stop(): void;
+}
+
+export type RedisServiceBinding = ServiceBinding;
+export type PgsqlServiceBinding = ServiceBinding;
+export type MysqlServiceBinding = ServiceBinding;
+export type WireServiceBinding = ServiceBinding;
+
+export interface NodeStatusBinding {
+    directory: string;
+    ownership: string;
+    health: string;
+    identity: string;
+    runtime: string | null;
+}

package/src/node/cluster.ts

@@ -1,56 +1,53 @@
-import { spawn } from "node:child_process";
-
-export type YydsProtocol = "redis" | "mysql" | "postgresql";
-
-const portFlags: Record<YydsProtocol, string> = {
-    redis: "--redis-port",
-    mysql: "--mysql-port",
-    postgresql: "--pgsql-port",
-};
-const defaultPorts: Partial<Record<YydsProtocol, number>> = { mysql: 3306, postgresql: 5432 };
-
-export function yydsStartArguments(protocol: YydsProtocol, args: string[]): string[] {
-    const result = ["start"];
-    let protocolPortProvided = false;
-    for (let index = 0; index < args.length; index += 1) {
-        const argument = args[index];
-        if (["--port", "-p", "-P"].includes(argument)) {
-            const value = args[++index];
-            if (value === undefined || value.startsWith("-"))
-                throw new Error(`missing port after ${argument}`);
-            result.push(portFlags[protocol], value);
-            protocolPortProvided = true;
-        } else {
-            result.push(argument);
-            if (argument === portFlags[protocol]) protocolPortProvided = true;
-        }
-    }
-    const defaultPort = defaultPorts[protocol];
-    if (!protocolPortProvided && defaultPort !== undefined)
-        result.push(portFlags[protocol], String(defaultPort));
-    return result;
-}
-
-export function launchYydsServer(protocol: YydsProtocol, args: string[]): Promise<number> {
-    const executable = process.env.YYDS_CLI_PATH || "yyds";
-    const child = spawn(executable, yydsStartArguments(protocol, args), {
-        stdio: "inherit",
-        windowsHide: true,
-    });
-    const forward = (signal: NodeJS.Signals) => child.kill(signal);
-    const onInterrupt = () => forward("SIGINT");
-    const onTerminate = () => forward("SIGTERM");
-    process.once("SIGINT", onInterrupt);
-    process.once("SIGTERM", onTerminate);
-
-    return new Promise((resolve, reject) => {
-        child.once("error", (error) =>
-            reject(new Error(`cannot start '${executable}': ${error.message}`)),
-        );
-        child.once("close", (code, signal) => {
-            process.removeListener("SIGINT", onInterrupt);
-            process.removeListener("SIGTERM", onTerminate);
-            resolve(code ?? (signal ? 1 : 0));
-        });
-    });
-}
+import type { StartNodeOptions } from "./runtime.ts";
+import { parseStartOptions, runNodeStart } from "./runtime.ts";
+
+export type YydsProtocol = "redis" | "mysql" | "postgresql";
+
+/** Maps disguise-server `--port` flags to protocol-specific yyds start flags. */
+export function yydsStartArguments(protocol: YydsProtocol, args: string[]): string[] {
+    const portFlags: Record<YydsProtocol, string> = {
+        redis: "--redis-port",
+        mysql: "--mysql-port",
+        postgresql: "--pgsql-port",
+    };
+    const defaultPorts: Partial<Record<YydsProtocol, number>> = {
+        mysql: 3306,
+        postgresql: 5432,
+    };
+    const normalized: string[] = [];
+    let sawPort = false;
+
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (["--port", "-p", "-P"].includes(argument)) {
+            const value = args[index + 1];
+            if (value === undefined || value.startsWith("--")) {
+                throw new Error(`missing port after ${argument}`);
+            }
+            normalized.push(portFlags[protocol], value);
+            sawPort = true;
+            index += 1;
+            continue;
+        }
+        normalized.push(argument);
+    }
+
+    const defaultPort = defaultPorts[protocol];
+    if (!sawPort && defaultPort !== undefined) {
+        normalized.push(portFlags[protocol], String(defaultPort));
+    }
+    return normalized;
+}
+
+/** Runs a node lifecycle in-process through orthogonal native blocks. */
+export async function launchYydsServer(protocol: YydsProtocol, args: string[]): Promise<number> {
+    try {
+        await runNodeStart(parseStartOptions(protocol, yydsStartArguments(protocol, args)));
+        return 0;
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(message);
+    }
+}
+
+export type { StartNodeOptions };

package/src/node/index.ts

@@ -1,20 +1,22 @@
-/**
- * `@yydb/yyds/node` — Node N-API facade.
- *
- * Browser code must use the default `@yydb/yyds` entry or `@yydb/yyds/wasm`.
- */
-
-export type { YydsBindings } from "../bindings.ts";
-export type { YydsProtocol } from "./cluster.ts";
-export { launchYydsServer, yydsStartArguments } from "./cluster.ts";
-export { isYydsNativeInstalled, loadYydsNative, loadYydsSqliteNative } from "./load.ts";
-export type {
-    SqliteConnectionBinding,
-    SqliteQueryResultBinding,
-    SqliteReadLimits,
-    SqliteResultValueBinding,
-    SqliteSchemaObject,
-    SqliteSnapshotBinding,
-    SqliteTableRow,
-    YydsSqliteBindings,
-} from "./sqlite-bindings.ts";
+/**
+ * `@yydb/yyds/node` — Node N-API facade.
+ *
+ * Browser hosts are not supported in this package yet.
+ */
+
+export type { YydsBindings, NodeStatusBinding, ServiceBinding } from "../bindings.ts";
+export type { YydsProtocol } from "./cluster.ts";
+export { launchYydsServer, yydsStartArguments } from "./cluster.ts";
+export { isYydsNativeInstalled, loadYydsNative, loadYydsSqliteNative } from "./load.ts";
+export type { StartNodeOptions } from "./runtime.ts";
+export { parseStartOptions, runNodeStart } from "./runtime.ts";
+export type {
+    SqliteDatabaseBinding,
+    SqliteDecodedRow,
+    SqliteReadLimits,
+    SqliteRecordValue,
+    SqliteSchemaObject,
+    SqliteSnapshotBinding,
+    SqliteTableRow,
+    YydsSqliteBindings,
+} from "./sqlite-bindings.ts";

package/src/node/load.ts

@@ -1,50 +1,48 @@
-import { createRequire } from "node:module";
-
-import type { YydsBindings } from "../bindings.ts";
-import { resolvePlatformPackage } from "./platform-packages.ts";
-import type { YydsSqliteBindings } from "./sqlite-bindings.ts";
-
-const require = createRequire(import.meta.url);
-
-function normalizeBinding(module: Record<string, unknown>): YydsBindings {
-    const binding = (module.default ?? module) as Record<string, unknown>;
-    return {
-        yydsVersion: () => String((binding.yydsVersion as () => string)()),
-        ping: () => String((binding.ping as () => string)()),
-    };
-}
-
-/** Load the platform-specific Node-API binding. */
-export function loadYydsNative(): YydsBindings {
-    const specifier = resolvePlatformPackage();
-    return normalizeBinding(require(specifier) as Record<string, unknown>);
-}
-
-/** Load the independent SQLite snapshot reader, not a YYDS execution session. */
-export function loadYydsSqliteNative(): YydsSqliteBindings {
-    const module = require(resolvePlatformPackage()) as Record<string, unknown>;
-    const binding = (module.default ?? module) as Record<string, unknown>;
-    if (
-        typeof binding.SqliteSnapshot !== "function" ||
-        typeof binding.SqliteConnection !== "function"
-    ) {
-        throw new Error(
-            "Native addon lacks the SQLite snapshot reader. Rebuild the native package.",
-        );
-    }
-    return {
-        SqliteSnapshot: binding.SqliteSnapshot as YydsSqliteBindings["SqliteSnapshot"],
-        SqliteConnection: binding.SqliteConnection as YydsSqliteBindings["SqliteConnection"],
-    };
-}
-
-/** Whether the current platform optional dependency is installed. */
-export function isYydsNativeInstalled(): boolean {
-    try {
-        resolvePlatformPackage();
-        require.resolve(resolvePlatformPackage());
-        return true;
-    } catch {
-        return false;
-    }
-}
+import { createRequire } from "node:module";
+
+import type { YydsBindings } from "../bindings.ts";
+import { resolvePlatformPackage } from "./platform-packages.ts";
+import type { YydsSqliteBindings } from "./sqlite-bindings.ts";
+
+const require = createRequire(import.meta.url);
+
+function bindingModule(): Record<string, unknown> {
+    const module = require(resolvePlatformPackage()) as Record<string, unknown>;
+    return (module.default ?? module) as Record<string, unknown>;
+}
+
+/** Load the platform-specific Node-API binding. */
+export function loadYydsNative(): YydsBindings {
+    const binding = bindingModule();
+    return binding as unknown as YydsBindings;
+}
+
+/** Load the independent SQLite snapshot reader, not a YYDS execution session. */
+export function loadYydsSqliteNative(): YydsSqliteBindings {
+    const binding = bindingModule();
+    if (typeof binding.SqliteSnapshot !== "function") {
+        throw new Error("Native addon lacks the SQLite snapshot reader. Rebuild the native package.");
+    }
+    if (typeof binding.SqliteDatabase !== "function") {
+        throw new Error("Native addon lacks the SqliteDatabase class. Rebuild the native package.");
+    }
+    if (typeof binding.decodeRecord !== "function") {
+        throw new Error("Native addon lacks decodeRecord. Rebuild the native package.");
+    }
+    return {
+        SqliteSnapshot: binding.SqliteSnapshot as YydsSqliteBindings["SqliteSnapshot"],
+        SqliteDatabase: binding.SqliteDatabase as unknown as YydsSqliteBindings["SqliteDatabase"],
+        decodeRecord: binding.decodeRecord as YydsSqliteBindings["decodeRecord"],
+    };
+}
+
+/** Whether the current platform optional dependency is installed. */
+export function isYydsNativeInstalled(): boolean {
+    try {
+        resolvePlatformPackage();
+        require.resolve(resolvePlatformPackage());
+        return true;
+    } catch {
+        return false;
+    }
+}

package/src/node/platform-packages.ts

@@ -1,15 +1,15 @@
-const PLATFORM_PACKAGES: Record<string, string> = {
-    "win32-x64": "@yydb/yyds-win32-x64",
-    "darwin-x64": "@yydb/yyds-darwin-x64",
-    "darwin-arm64": "@yydb/yyds-darwin-arm64",
-    "linux-x64": "@yydb/yyds-linux-x64",
-};
-
-export function resolvePlatformPackage(): string {
-    const key = `${process.platform}-${process.arch}`;
-    const specifier = PLATFORM_PACKAGES[key];
-    if (!specifier) {
-        throw new Error(`@yydb/yyds/node: unsupported platform ${key}`);
-    }
-    return specifier;
-}
+const PLATFORM_PACKAGES: Record<string, string> = {
+    "win32-x64": "@yydb/yyds-win32-x64",
+    "darwin-x64": "@yydb/yyds-darwin-x64",
+    "darwin-arm64": "@yydb/yyds-darwin-arm64",
+    "linux-x64": "@yydb/yyds-linux-x64",
+};
+
+export function resolvePlatformPackage(): string {
+    const key = `${process.platform}-${process.arch}`;
+    const specifier = PLATFORM_PACKAGES[key];
+    if (!specifier) {
+        throw new Error(`@yydb/yyds/node: unsupported platform ${key}`);
+    }
+    return specifier;
+}

package/src/node/runtime.ts

@@ -0,0 +1,127 @@
+import { setTimeout as sleep } from "node:timers/promises";
+
+import type { YydsProtocol } from "./cluster.ts";
+import { loadYydsNative } from "./load.ts";
+
+const DEFAULT_REDIS_PORT = 6379;
+
+export interface StartNodeOptions {
+    dataDir: string;
+    clusterId: string;
+    nodeId: string;
+    redisPort?: number;
+    pgsqlPort?: number;
+    mysqlPort?: number;
+    wirePort?: number;
+}
+
+export function parseStartOptions(protocol: YydsProtocol, args: string[]): StartNodeOptions {
+    const options: StartNodeOptions = {
+        dataDir: "",
+        clusterId: "",
+        nodeId: "",
+        redisPort: DEFAULT_REDIS_PORT,
+    };
+    const portFlags: Record<YydsProtocol, string> = {
+        redis: "--redis-port",
+        mysql: "--mysql-port",
+        postgresql: "--pgsql-port",
+    };
+    const defaultPorts: Partial<Record<YydsProtocol, number>> = { mysql: 3306, postgresql: 5432 };
+
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (["--port", "-p", "-P"].includes(argument)) {
+            const value = Number(args[++index]);
+            if (!Number.isInteger(value) || value < 0) throw new Error(`missing port after ${argument}`);
+            if (protocol === "redis") options.redisPort = value;
+            if (protocol === "mysql") options.mysqlPort = value;
+            if (protocol === "postgresql") options.pgsqlPort = value;
+            continue;
+        }
+        if (argument === "--data-dir") {
+            options.dataDir = args[++index] ?? "";
+            continue;
+        }
+        if (argument === "--cluster-id") {
+            options.clusterId = args[++index] ?? "";
+            continue;
+        }
+        if (argument === "--node-id") {
+            options.nodeId = args[++index] ?? "";
+            continue;
+        }
+        if (argument === "--redis-port") {
+            options.redisPort = Number(args[++index]);
+            continue;
+        }
+        if (argument === "--pgsql-port") {
+            options.pgsqlPort = Number(args[++index]);
+            continue;
+        }
+        if (argument === "--mysql-port") {
+            options.mysqlPort = Number(args[++index]);
+            continue;
+        }
+        if (argument === "--wire-port") {
+            options.wirePort = Number(args[++index]);
+            continue;
+        }
+        throw new Error(`unknown option '${argument}'`);
+    }
+
+    if (!options.dataDir || !options.clusterId || !options.nodeId) {
+        throw new Error("start requires --data-dir, --cluster-id, and --node-id");
+    }
+    const defaultPort = defaultPorts[protocol];
+    if (protocol === "mysql" && options.mysqlPort === undefined && defaultPort !== undefined) {
+        options.mysqlPort = defaultPort;
+    }
+    if (protocol === "postgresql" && options.pgsqlPort === undefined && defaultPort !== undefined) {
+        options.pgsqlPort = defaultPort;
+    }
+    return options;
+}
+
+/** Starts protocol listeners for one node directory and blocks until stop is requested. */
+export async function runNodeStart(options: StartNodeOptions): Promise<void> {
+    const native = loadYydsNative();
+    const identity = new native.NodeIdentityHandle(options.clusterId, options.nodeId);
+    const lease = native.NodeLeaseHandle.acquire(options.dataDir, identity);
+    const executor = new native.LocalExecutorHandle(options.dataDir);
+    const redis = new native.RedisServiceHandle(lease, options.redisPort ?? DEFAULT_REDIS_PORT, executor);
+    const pgsql = options.pgsqlPort === undefined ? undefined : new native.PgsqlServiceHandle(lease, options.pgsqlPort);
+    const mysql = options.mysqlPort === undefined ? undefined : new native.MysqlServiceHandle(lease, options.mysqlPort);
+    const wire = options.wirePort === undefined ? undefined : new native.WireServerHandle(options.wirePort, executor);
+
+    const runtime = {
+        version: 1,
+        generation: crypto.randomUUID(),
+        pid: process.pid,
+        startedAtUnixMs: Date.now(),
+        redisAddress: redis.address(),
+        pgsqlAddress: pgsql?.address(),
+        mysqlAddress: mysql?.address(),
+        wireAddress: wire?.address(),
+    };
+    native.nodeWriteRuntimeStatus(options.dataDir, JSON.stringify(runtime));
+
+    process.stdout.write(
+        `yyds running pid=${runtime.pid} redis=${runtime.redisAddress} pgsql=${runtime.pgsqlAddress ?? "null"} mysql=${runtime.mysqlAddress ?? "null"} wire=${runtime.wireAddress ?? "null"}\n`,
+    );
+
+    while (true) {
+        if (native.nodeStopRequested(options.dataDir, runtime.generation)) break;
+        if (redis.isFinished()) break;
+        if (pgsql?.isFinished()) break;
+        if (mysql?.isFinished()) break;
+        if (wire?.isFinished()) break;
+        await sleep(50);
+    }
+
+    redis.stop();
+    pgsql?.stop();
+    mysql?.stop();
+    wire?.stop();
+    native.nodeClearRuntimeArtifacts(options.dataDir, runtime.generation);
+}

package/src/node/sqlite-bindings.ts

@@ -1,64 +1,70 @@
-/** Bounds apply independently to each schema or table scan. */
-export interface SqliteReadLimits {
-    maxPages?: number;
-    maxRows?: number;
-    maxPayloadBytes?: number;
-    maxTotalPayloadBytes?: number;
-}
-
-/** SQL source is opaque. No CREATE statement is parsed or executed. */
-export interface SqliteSchemaObject {
-    kind: "table" | "index" | "view" | "trigger";
-    name: string;
-    tableName: string;
-    rootPage?: number;
-    sql?: string;
-}
-
-/** Raw storage values, not SQL results or INTEGER PRIMARY KEY expansion. */
-export interface SqliteTableRow {
-    rowid: bigint;
-    payload: Buffer;
-}
-
-export interface SqliteSnapshotBinding {
-    schema(limits?: SqliteReadLimits): SqliteSchemaObject[];
-    table(name: string, limits?: SqliteReadLimits): SqliteTableRow[];
-}
-
-/** An independent SQLite reader hosted in the same native addon. */
-export interface YydsSqliteBindings {
-    SqliteSnapshot: new (bytes: Buffer, maxSnapshotBytes?: number) => SqliteSnapshotBinding;
-    SqliteConnection: new (path: string, readOnly?: boolean) => SqliteConnectionBinding;
-}
-
-export interface SqliteConnectionBinding {
-    execute(sql: string): SqliteQueryResultBinding;
-    executeWithParameters(sql: string, parameters: SqliteParameterBinding[]): SqliteQueryResultBinding;
-    executeBatch(sql: string): void;
-    sourceId(): string;
-}
-
-export interface SqliteParameterBinding {
-    kind: "null" | "integer" | "real" | "text" | "blob";
-    integer?: string;
-    real?: number;
-    text?: Buffer;
-    blob?: Buffer;
-}
-
-export interface SqliteQueryResultBinding {
-    columns: string[];
-    rows: SqliteResultValueBinding[][];
-    changes: string;
-    lastInsertRowid: string;
-}
-
-export interface SqliteResultValueBinding {
-    kind: "null" | "integer" | "real" | "text" | "blob";
-    integer?: string;
-    real?: number;
-    text?: string;
-    textBytes?: Buffer;
-    blob?: Buffer;
-}
+/** Bounds apply independently to each schema or table scan. */
+export interface SqliteReadLimits {
+    maxPages?: number;
+    maxRows?: number;
+    maxPayloadBytes?: number;
+    maxTotalPayloadBytes?: number;
+}
+
+/** SQL source is opaque. No CREATE statement is parsed or executed. */
+export interface SqliteSchemaObject {
+    kind: "table" | "index" | "view" | "trigger";
+    name: string;
+    tableName: string;
+    rootPage?: number;
+    sql?: string;
+}
+
+/** Raw storage values, not SQL results or INTEGER PRIMARY KEY expansion. */
+export interface SqliteTableRow {
+    rowid: bigint;
+    payload: Buffer;
+}
+
+/** One decoded SQLite storage-class field. Exactly one `value*` is populated. */
+export interface SqliteRecordValue {
+    kind: "null" | "integer" | "real" | "text" | "blob";
+    valueInteger?: bigint;
+    valueReal?: number;
+    valueText?: string;
+    valueBlob?: Buffer;
+}
+
+/** A decoded SQLite row with storage-class typed columns. */
+export interface SqliteDecodedRow {
+    rowid: bigint;
+    columns: SqliteRecordValue[];
+}
+
+/** Binding surface for SqliteSnapshot (read-only main-file buffer). */
+export interface SqliteSnapshotBinding {
+    schema(limits?: SqliteReadLimits): SqliteSchemaObject[];
+    table(name: string, limits?: SqliteReadLimits): SqliteTableRow[];
+    tableDecoded(name: string, limits?: SqliteReadLimits): SqliteDecodedRow[];
+    sqliteVersion(): string;
+    encoding(): string;
+    ping(): number;
+    pages(): Buffer;
+}
+
+/** Binding surface for SqliteDatabase (file-backed or in-memory handle). */
+export interface SqliteDatabaseBinding {
+    path(): string | null;
+    ping(): number;
+    sqliteVersion(): string;
+    encoding(): string;
+    schema(limits?: SqliteReadLimits): SqliteSchemaObject[];
+    table(name: string, limits?: SqliteReadLimits): SqliteDecodedRow[];
+    tableRaw(name: string, limits?: SqliteReadLimits): SqliteTableRow[];
+    pages(): Buffer;
+}
+
+/** Combined SQLite native addon surface. */
+export interface YydsSqliteBindings {
+    SqliteSnapshot: new (bytes: Buffer, maxSnapshotBytes?: number) => SqliteSnapshotBinding;
+    SqliteDatabase: {
+        openInMemory(): SqliteDatabaseBinding;
+        open(path: string): SqliteDatabaseBinding;
+    };
+    decodeRecord(payload: Buffer, encoding?: string): SqliteRecordValue[];
+}

package/src/node/unsupported.ts

@@ -1 +1 @@
-throw new Error("@yydb/yyds/node is only available in Node.js runtimes");
+throw new Error("@yydb/yyds/node is only available in Node.js runtimes");

package/src/browser/index.ts

@@ -1,7 +0,0 @@
-/**
- * `@yydb/yyds` default export — browser / Worker facade (WASM inside).
- *
- * Node apps use `@yydb/yyds/node`. Low-level WASM loader: `@yydb/yyds/wasm`.
- */
-
-export { initWasm, ping, yydsVersion, type InitWasmOptions, type WasmInitInput } from "../wasm/index.ts";

package/src/wasm/index.ts

@@ -1,8 +0,0 @@
-export {
-    initWasm,
-    ping,
-    resetWasmBindingForTests,
-    yydsVersion,
-    type InitWasmOptions,
-    type WasmInitInput,
-} from "@yydb/yyds-unknown-wasm32";