@yydb/yydb 0.0.4 → 0.0.6

package/README.md

@@ -1,29 +1,36 @@
 # `@yydb/yydb`
 
-Opens a `.yydb` file in Node.js with one dependency: a private loopback `yydb serve` process starts automatically and
-the package talks to it over the YY wire protocol. For a lightweight client only (browser, renderer, or an app that
-already runs `yydb serve`), use [`@yydb/yydb-client`](https://www.npmjs.com/package/@yydb/yydb-client).
+Node all-in-one and browser wasm core from one package. On Node.js, `Database.open` starts a private loopback `yydb serve`
+process and talks over the YY wire protocol. In browsers, `@yydb/yydb/wasm` loads an in-process wasm session with KV
+and schema on memory or OPFS paths.
+
+For a wire client only (renderer or an app that already runs `yydb serve`), use
+[`@yydb/yydb-client`](https://www.npmjs.com/package/@yydb/yydb-client).
 
 [![npm](https://img.shields.io/npm/v/@yydb/yydb)](https://www.npmjs.com/package/@yydb/yydb)
 [![Node.js](https://img.shields.io/node/v/@yydb/yydb)](https://www.npmjs.com/package/@yydb/yydb)
 
 ## Exports
 
-| Import           | Role                                     |
-|------------------|------------------------------------------|
-| `@yydb/yydb`     | `Database` API and default entry         |
-| `@yydb/yydb/cli` | CLI (`version`, `init`, `info`, `serve`) |
+| Import | Runtime | Role |
+|--------|---------|------|
+| `@yydb/yydb` | Node (`node` export condition) | `Database.open`, micro helpers |
+| `@yydb/yydb` | Browser / bundler (`default`) | wasm `Database` |
+| `@yydb/yydb/node` | Node (explicit) | Same as Node default |
+| `@yydb/yydb/wasm` | Browser (explicit) | wasm `Database`, `initWasm`, `checkSchema` |
+| `@yydb/yydb/cli` | Node | CLI (`version`, `init`, `info`, `serve`) |
 
-Node.js 18+. The matching platform `.node` binding installs via optional dependencies.
+Node.js 18+. Platform `.node` bindings install via optional dependencies.
 
-Schema truth lives in the `.yydb` file via `ensureSchema` and VOS documents.
+Schema truth lives in the `.yydb` file via `ensureSchema` and VOS documents. Wasm sessions mirror KV and schema calls
+on the embedded core.
 
-## Example
+## Node example
 
 ```ts
-import {Database} from "@yydb/yydb";
+import { Database } from '@yydb/yydb';
 
-const db = await Database.open("./data/app.yydb");
+const db = await Database.open('./data/app.yydb');
 
 await db.ensureSchema(
     1,
@@ -34,14 +41,54 @@ await db.ensureSchema(
     }`,
 );
 
-await db.put("theme", "dark");
-console.log(await db.get("theme"));
+await db.put('theme', 'dark');
+console.log(await db.get('theme'));
 await db.close();
 ```
 
 The file is created when missing. Schema version and VOS document persist with the data.
 
-## API
+## Browser example
+
+```ts
+import { Database } from '@yydb/yydb/wasm';
+
+const db = await Database.openInMemory();
+
+await db.ensureSchema(
+    1,
+    `table Setting {
+        @@id: uuid,
+        key: utf8,
+        value: utf8,
+    }`,
+);
+
+await db.put('theme', 'dark');
+console.log(await db.get('theme'));
+db.close();
+```
+
+Use `Database.open('app.yydb')` for OPFS-backed paths in supported browsers.
+
+## Wasm API
+
+```ts
+const db = await Database.openInMemory();
+// or: const db = await Database.open('app.yydb');
+
+await db.ensureSchema(version, vosDocument);
+await db.getSchema();
+await db.put(key, stringOrBytes);
+await db.get(key);
+await db.info();
+await db.serverVersion();
+await db.registerMicro(microDefinition);
+await db.callScalar('double', 1, [21]);
+db.close();
+```
+
+## Node API
 
 ```ts
 const db = await Database.open(path, options?);
@@ -52,6 +99,8 @@ await db.put(key, stringOrBytes);
 await db.get(key);
 await db.info();
 await db.serverVersion();
+await db.registerMicro(microDefinition);
+await db.callScalar('double', 1, [21]);
 await db.close();
 ```
 
@@ -60,14 +109,15 @@ arguments). `binary` is a deprecated alias for `cli`.
 
 ## Related packages
 
-| Need                           | Package                                                                |
-|--------------------------------|------------------------------------------------------------------------|
-| Node all-in-one (this package) | **`@yydb/yydb`**                                                       |
-| Wire client only               | [`@yydb/yydb-client`](https://www.npmjs.com/package/@yydb/yydb-client) |
-| In-process Rust embed          | [`yydb`](https://crates.io/crates/yydb)                                |
-| Agent skills (wire protocol)   | [`@yydb/yydb-skills`](https://www.npmjs.com/package/@yydb/yydb-skills) |
+| Need | Package |
+|------|---------|
+| Node all-in-one (this package) | **`@yydb/yydb`** or `@yydb/yydb/node` |
+| Browser wasm entry | **`@yydb/yydb/wasm`** |
+| Wire client only | [`@yydb/yydb-client`](https://www.npmjs.com/package/@yydb/yydb-client) |
+| In-process Rust embed | [`yydb`](https://crates.io/crates/yydb) |
+| Agent skills (wire protocol) | [`@yydb/yydb-skills`](https://www.npmjs.com/package/@yydb/yydb-skills) |
 
-Electron: main process can use `@yydb/yydb`; renderer code can use `@yydb/yydb-client` against the main-process
+Electron: main process can use `@yydb/yydb/node`; renderer code can use `@yydb/yydb-client` against the main-process
 endpoint.
 
 The managed engine listens on `127.0.0.1` with no authentication — keep the endpoint private.

package/dist/{cli → node/cli}/cli.js

@@ -6,7 +6,7 @@ import { registerInitCommand } from './init-cmd.js';
 import { registerServeCommand } from './serve-cmd.js';
 import { registerVersionCommand } from './version-cmd.js';
 function buildYydbCli() {
-    const localesRoot = join(dirname(fileURLToPath(import.meta.url)), '../../locales');
+    const localesRoot = join(dirname(fileURLToPath(import.meta.url)), '../../../locales');
     const cli = createCli('yydb').locales(localesRoot).intro('cli.intro');
     registerVersionCommand(cli);
     registerInitCommand(cli);

package/dist/{database.d.ts → node/database.d.ts}

@@ -1,5 +1,5 @@
-import { defineMicro as buildMicro, type DefinedMicro, type MicroHandle } from './micro.js';
-import type { UdfTypeDescriptor } from './udf-types.js';
+import { defineMicro as buildMicro, type DefinedMicro, type MicroHandle } from '../shared/micro.js';
+import type { UdfScalarDescriptor } from '../shared/udf-types.js';
 export type { SchemaVersion } from '@yydb/yydb-client';
 export interface OpenOptions {
     /** Override CLI script path (tests / special installs). */
@@ -36,13 +36,13 @@ export declare class Database {
      * Build a typed session-local micro definition. Does not register it with
      * the engine until [`registerMicro`](./database.ts) is called.
      */
-    defineMicro<TArgs extends readonly UdfTypeDescriptor[], TReturn extends UdfTypeDescriptor>(definition: Parameters<typeof buildMicro<TArgs, TReturn>>[0]): DefinedMicro<TArgs, TReturn>;
+    defineMicro<TArgs extends readonly UdfScalarDescriptor[], TReturn extends UdfScalarDescriptor>(definition: Parameters<typeof buildMicro<TArgs, TReturn>>[0]): DefinedMicro<TArgs, TReturn>;
     /**
      * Install a [`defineMicro`](./database.ts) definition into the current
      * session registry and sync metadata to the private engine. Host micros are
      * session-local and never written to `.yydb`.
      */
-    registerMicro<TArgs extends readonly UdfTypeDescriptor[], TReturn extends UdfTypeDescriptor>(definition: DefinedMicro<TArgs, TReturn>): Promise<MicroHandle>;
+    registerMicro<TArgs extends readonly UdfScalarDescriptor[], TReturn extends UdfScalarDescriptor>(definition: DefinedMicro<TArgs, TReturn>): Promise<MicroHandle>;
     /** Invoke a registered scalar UDF on the private engine. */
     callScalar(name: string, version: number, args: readonly (string | number | boolean | null)[]): Promise<string | number | boolean | null>;
     /** Stop the private engine process. */

package/dist/{database.js → node/database.js}

@@ -3,16 +3,8 @@ import fs from 'node:fs';
 import net from 'node:net';
 import path from 'node:path';
 import { connect } from '@yydb/yydb-client/node';
-import { defineMicro as buildMicro, MicroSessionRegistry } from './micro.js';
+import { defineMicro as buildMicro, microFingerprint, udfWireKind, MicroSessionRegistry, } from '../shared/micro.js';
 import { resolveYydbCli } from './resolve-bin.js';
-function microFingerprint(name, version) {
-    const bytes = new Uint8Array(32);
-    const seed = `${name}@${version}`;
-    for (let index = 0; index < bytes.byteLength; index += 1) {
-        bytes[index] = seed.charCodeAt(index % seed.length) & 0xff;
-    }
-    return bytes;
-}
 async function freeLoopbackPort() {
     return await new Promise((resolve, reject) => {
         const server = net.createServer();
@@ -149,8 +141,8 @@ export class Database {
             udfVersion: definition.version,
             name: definition.name,
             functionId: handle.functionId,
-            args: definition.args.map((arg) => arg.kind),
-            returns: definition.returns.kind,
+            args: definition.args.map(udfWireKind),
+            returns: udfWireKind(definition.returns),
             fingerprint: microFingerprint(definition.name, definition.version),
         });
         return handle;

package/dist/node/index.d.ts

@@ -0,0 +1,7 @@
+export { Database, type OpenOptions } from './database.js';
+export { YydbError, YydbErrorCodes, isRetryableYydbCode, isYydbError } from '@yydb/yydb-client';
+export type { YydbErrorCode, YydbErrorOptions } from '@yydb/yydb-client';
+export { defineMicro, type DefinedMicro, type MicroHandle, type TsMicroDefinitionInput, MicroSessionRegistry } from '../shared/micro.js';
+export { type InferUdfArgs, type InferUdfReturn, type MicroEffect, type MicroInvocationMode, type UdfScalarDescriptor, type UdfScalarKind, } from '../shared/udf-types.js';
+export { nativeBindingName, platformKey, resolveYydbBinary, resolveYydbCli } from './resolve-bin.js';
+export * from '../shared/vos.js';

package/dist/node/index.js

@@ -0,0 +1,5 @@
+export { Database } from './database.js';
+export { YydbError, YydbErrorCodes, isRetryableYydbCode, isYydbError } from '@yydb/yydb-client';
+export { defineMicro, MicroSessionRegistry } from '../shared/micro.js';
+export { nativeBindingName, platformKey, resolveYydbBinary, resolveYydbCli } from './resolve-bin.js';
+export * from '../shared/vos.js';

package/dist/{micro.d.ts → shared/micro.d.ts}

@@ -1,6 +1,19 @@
-import type { InferUdfArgs, InferUdfReturn, MicroEffect, MicroInvocationMode, UdfTypeDescriptor } from './udf-types.js';
+import type { InferUdfArgs, InferUdfReturn, MicroEffect, MicroInvocationMode, UdfScalarDescriptor } from './udf-types.js';
+import type { AnyTypeDescriptor } from '@voml/vos';
+/** Value shape accepted and produced on the wire micro path. */
+type MicroWireValue = string | number | boolean | null;
+/** Wire kinds a VOS descriptor can map onto (`UdfType::Null` is never a type here). */
+type UdfWireKind = 'i64' | 'bool' | 'text';
+/**
+ * Maps a VOS descriptor onto its wire `UdfType` tag.
+ *
+ * Accepts any VOS descriptor so the runtime layer can reject a kind that
+ * slipped past the type layer; throws for everything outside the Phase-1
+ * subset instead of letting it reach the engine.
+ */
+export declare function udfWireKind(descriptor: AnyTypeDescriptor): UdfWireKind;
 /** Input accepted by [`Database.defineMicro`](./database.ts). */
-export interface TsMicroDefinitionInput<TArgs extends readonly UdfTypeDescriptor[], TReturn extends UdfTypeDescriptor> {
+export interface TsMicroDefinitionInput<TArgs extends readonly UdfScalarDescriptor[], TReturn extends UdfScalarDescriptor> {
     readonly name: string;
     readonly version: number;
     readonly args: TArgs;
@@ -11,7 +24,7 @@ export interface TsMicroDefinitionInput<TArgs extends readonly UdfTypeDescriptor
     readonly fn: (...args: InferUdfArgs<TArgs>) => InferUdfReturn<TReturn>;
 }
 /** Opaque definition produced by `defineMicro` before session registration. */
-export interface DefinedMicro<TArgs extends readonly UdfTypeDescriptor[] = readonly UdfTypeDescriptor[], TReturn extends UdfTypeDescriptor = UdfTypeDescriptor> {
+export interface DefinedMicro<TArgs extends readonly UdfScalarDescriptor[] = readonly UdfScalarDescriptor[], TReturn extends UdfScalarDescriptor = UdfScalarDescriptor> {
     readonly name: string;
     readonly version: number;
     readonly args: TArgs;
@@ -31,7 +44,7 @@ export interface MicroHandle {
     /** Monotonic host implementation version for opaque handle checks. */
     readonly implementationVersion: number;
 }
-type AnyDefinedMicro = DefinedMicro<readonly UdfTypeDescriptor[], UdfTypeDescriptor>;
+type AnyDefinedMicro = DefinedMicro<readonly UdfScalarDescriptor[], UdfScalarDescriptor>;
 /**
  * Process-local registry for JS functions behind opaque host handles.
  * Rust keeps `host_id + function_id + version`, not the closure.
@@ -43,7 +56,7 @@ export declare class MicroSessionRegistry {
     private readonly byFunctionId;
     constructor(hostId?: number);
     /** Installs a defined micro into the current session registry. */
-    register<TArgs extends readonly UdfTypeDescriptor[], TReturn extends UdfTypeDescriptor>(definition: DefinedMicro<TArgs, TReturn>): MicroHandle;
+    register<TArgs extends readonly UdfScalarDescriptor[], TReturn extends UdfScalarDescriptor>(definition: DefinedMicro<TArgs, TReturn>): MicroHandle;
     /** Returns a registered micro by opaque host handle. */
     resolve(handle: MicroHandle): AnyDefinedMicro | undefined;
     /** Invokes a registered micro from a wire `MicroHostInvoke` payload. */
@@ -52,12 +65,14 @@ export declare class MicroSessionRegistry {
         handleVersion: number;
         functionId: string;
         args: readonly unknown[];
-    }): string | number | boolean | null;
+    }): MicroWireValue;
     /** Invokes a registered scalar micro (host adapter entry point). */
     invokeScalar(handle: MicroHandle, args: unknown[]): unknown;
     /** Lists logical names currently registered in this session. */
     list(): string[];
 }
 /** Builds a session-local micro definition without registering it. */
-export declare function defineMicro<TArgs extends readonly UdfTypeDescriptor[], TReturn extends UdfTypeDescriptor>(input: TsMicroDefinitionInput<TArgs, TReturn>): DefinedMicro<TArgs, TReturn>;
+export declare function defineMicro<TArgs extends readonly UdfScalarDescriptor[], TReturn extends UdfScalarDescriptor>(input: TsMicroDefinitionInput<TArgs, TReturn>): DefinedMicro<TArgs, TReturn>;
+/** Stable 32-byte fingerprint for a logical micro name and version. */
+export declare function microFingerprint(name: string, version: number): Uint8Array;
 export {};

package/dist/{micro.js → shared/micro.js}

@@ -1,3 +1,22 @@
+/**
+ * Maps a VOS descriptor onto its wire `UdfType` tag.
+ *
+ * Accepts any VOS descriptor so the runtime layer can reject a kind that
+ * slipped past the type layer; throws for everything outside the Phase-1
+ * subset instead of letting it reach the engine.
+ */
+export function udfWireKind(descriptor) {
+    switch (descriptor.kind) {
+        case 'i64':
+            return 'i64';
+        case 'bool':
+            return 'bool';
+        case 'utf8':
+            return 'text';
+        default:
+            throw new Error(`unsupported micro type descriptor: ${descriptor.kind}`);
+    }
+}
 let nextHostId = 1;
 /**
  * Process-local registry for JS functions behind opaque host handles.
@@ -46,7 +65,12 @@ export class MicroSessionRegistry {
             name: '',
             version: 0,
         };
-        return this.invokeScalar(handle, [...payload.args]);
+        const definition = this.resolve(handle);
+        if (!definition) {
+            throw new Error(`micro not found: ${payload.functionId}`);
+        }
+        const args = definition.args.map((descriptor, index) => wireToBoundary(descriptor, payload.args[index]));
+        return boundaryToWire(definition.returns, this.invokeScalar(handle, args));
     }
     /** Invokes a registered scalar micro (host adapter entry point). */
     invokeScalar(handle, args) {
@@ -60,9 +84,11 @@ export class MicroSessionRegistry {
         if (args.length !== definition.args.length) {
             throw new Error(`micro ${definition.name} arity mismatch: expected ${definition.args.length}, got ${args.length}`);
         }
-        validateArgTypes(definition, args);
+        definition.args.forEach((descriptor, index) => {
+            validateValue(descriptor, args[index], `micro ${definition.name} arg ${index}`);
+        });
         const result = definition.fn(...args);
-        validateReturnType(definition.returns, result);
+        validateValue(definition.returns, result, `micro ${definition.name} return`);
         return result;
     }
     /** Lists logical names currently registered in this session. */
@@ -87,6 +113,12 @@ export function defineMicro(input) {
     if (typeof input.fn !== 'function') {
         throw new Error('micro fn must be a function');
     }
+    // Reject descriptors outside the Phase-1 subset while the definition is
+    // still session-local, instead of at register time.
+    input.args.forEach((descriptor, index) => {
+        assertSupportedDescriptor(descriptor, `micro ${input.name} arg ${index}`);
+    });
+    assertSupportedDescriptor(input.returns, `micro ${input.name} return`);
     return {
         name: input.name,
         version: input.version,
@@ -99,62 +131,63 @@ export function defineMicro(input) {
         fn: input.fn,
     };
 }
+/** Stable 32-byte fingerprint for a logical micro name and version. */
+export function microFingerprint(name, version) {
+    const bytes = new Uint8Array(32);
+    const seed = `${name}@${version}`;
+    for (let index = 0; index < bytes.byteLength; index += 1) {
+        bytes[index] = seed.charCodeAt(index % seed.length) & 0xff;
+    }
+    return bytes;
+}
 function logicalKey(name, version) {
     return `${name}@${version}`;
 }
-function validateArgTypes(definition, args) {
-    for (let index = 0; index < definition.args.length; index += 1) {
-        const kind = definition.args[index]?.kind;
-        const value = args[index];
-        switch (kind) {
-            case 'i64':
-                if (typeof value !== 'number' || !Number.isInteger(value)) {
-                    throw new Error(`micro ${definition.name} arg ${index} expects i64`);
-                }
-                break;
-            case 'bool':
-                if (typeof value !== 'boolean') {
-                    throw new Error(`micro ${definition.name} arg ${index} expects bool`);
-                }
-                break;
-            case 'text':
-                if (typeof value !== 'string') {
-                    throw new Error(`micro ${definition.name} arg ${index} expects text`);
-                }
-                break;
-            case 'null':
-                if (value !== null) {
-                    throw new Error(`micro ${definition.name} arg ${index} expects null`);
-                }
-                break;
-            default:
-                throw new Error(`unsupported micro arg kind: ${kind}`);
-        }
+function assertSupportedDescriptor(descriptor, label) {
+    try {
+        udfWireKind(descriptor);
+    }
+    catch {
+        throw new Error(`${label} uses a descriptor outside the Phase-1 micro subset`);
     }
 }
-function validateReturnType(descriptor, value) {
-    switch (descriptor.kind) {
+/** Boundary value a VOS descriptor carries in the host runtime. */
+function validateValue(descriptor, value, label) {
+    switch (udfWireKind(descriptor)) {
         case 'i64':
-            if (typeof value !== 'number' || !Number.isInteger(value)) {
-                throw new Error('micro return expects i64');
+            if (typeof value !== 'bigint') {
+                throw new Error(`${label} expects VOS \`i64\` (a bigint)`);
             }
             break;
         case 'bool':
             if (typeof value !== 'boolean') {
-                throw new Error('micro return expects bool');
+                throw new Error(`${label} expects VOS \`bool\``);
             }
             break;
         case 'text':
             if (typeof value !== 'string') {
-                throw new Error('micro return expects text');
+                throw new Error(`${label} expects VOS \`utf8\` (a string)`);
             }
             break;
-        case 'null':
-            if (value !== null) {
-                throw new Error('micro return expects null');
-            }
-            break;
-        default:
-            throw new Error(`unsupported micro return kind: ${descriptor.kind}`);
     }
 }
+/**
+ * Wire value to boundary value. The YY wire carries `i64` as a JS number, so
+ * it becomes the VOS `i64` boundary value here rather than in author code.
+ */
+function wireToBoundary(descriptor, value) {
+    if (udfWireKind(descriptor) === 'i64' && typeof value === 'number' && Number.isSafeInteger(value)) {
+        return BigInt(value);
+    }
+    return value;
+}
+/** Boundary value back to the wire subset; `i64` must still fit a JS number. */
+function boundaryToWire(descriptor, value) {
+    if (udfWireKind(descriptor) === 'i64' && typeof value === 'bigint') {
+        if (value > BigInt(Number.MAX_SAFE_INTEGER) || value < BigInt(Number.MIN_SAFE_INTEGER)) {
+            throw new Error(`micro return i64 ${value} does not fit the wire number path`);
+        }
+        return Number(value);
+    }
+    return value;
+}

package/dist/shared/udf-types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Host micro (UDF) boundary types.
+ *
+ * Descriptors come straight from `@voml/vos`: `v.i64()`, `v.bool()`, `v.utf8()`.
+ * YYDB keeps no scalar descriptor algebra of its own — only the VOS descriptors
+ * the Phase-1 UDF boundary accepts.
+ *
+ * `null` is not a type here. It is a value carried by the wire subset, so it
+ * gets no descriptor.
+ *
+ * This module is types only, so a host test can load it through type stripping.
+ * The mapping onto the wire `UdfType` tags lives in `micro.ts`.
+ */
+import type { Infer, TypeDescriptor } from '@voml/vos';
+/** Phase-1 scalar kinds on the YY wire micro path, aligned with `yydb-udf`. */
+export type UdfScalarKind = 'i64' | 'bool' | 'text' | 'null';
+/**
+ * VOS descriptors accepted at the Phase-1 host micro boundary.
+ *
+ * Drawn from the frozen VOS type algebra, so `v.utf16()`, `v.optional(…)`,
+ * `v.list(…)` and every non-scalar descriptor are rejected before they reach
+ * the wire.
+ */
+export type UdfScalarDescriptor = TypeDescriptor<'i64', bigint> | TypeDescriptor<'bool', boolean> | TypeDescriptor<'utf8', string>;
+/** Maps a descriptor tuple to positional boundary value types. */
+export type InferUdfArgs<T extends readonly UdfScalarDescriptor[]> = {
+    [K in keyof T]: Infer<T[K]>;
+};
+/** Maps a return descriptor to its boundary value type. */
+export type InferUdfReturn<T extends UdfScalarDescriptor> = Infer<T>;
+/** Session micro effect surface (Phase 1: pure only). */
+export type MicroEffect = 'pure';
+/** Invocation mode stored with the definition for future batch host calls. */
+export type MicroInvocationMode = 'scalar' | 'batch';

package/dist/shared/udf-types.js

@@ -0,0 +1,14 @@
+/**
+ * Host micro (UDF) boundary types.
+ *
+ * Descriptors come straight from `@voml/vos`: `v.i64()`, `v.bool()`, `v.utf8()`.
+ * YYDB keeps no scalar descriptor algebra of its own — only the VOS descriptors
+ * the Phase-1 UDF boundary accepts.
+ *
+ * `null` is not a type here. It is a value carried by the wire subset, so it
+ * gets no descriptor.
+ *
+ * This module is types only, so a host test can load it through type stripping.
+ * The mapping onto the wire `UdfType` tags lives in `micro.ts`.
+ */
+export {};

package/dist/shared/vos.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `@yydb/yydb` 对 `@voml/vos` 的 re-export 门。
+ *
+ * 普通 YYDB 用户只依赖 `@yydb/yydb`，不必再显式安装或引入 `@voml/vos`。
+ * 这里只转发 YYDB 作者面需要的 VOS 建模面：`v` builder、descriptor 类型与 `Infer` 推导。
+ *
+ * 刻意不转发：
+ * - VOS source 发射：`@voml/vos` 不生成 `.vos` 文本（descriptor 直接编译 canonical artifact），
+ *   源码书写与格式化属于 `@voml/vos-language`。
+ * - `checkSource` / `VosDiagnostic`：VOS source 检查与语言层诊断属于 `@voml/vos-language`，
+ *   不属于 `@voml/vos` 建模面，也不进 YYDB 作者面。
+ *
+ * 依赖边界见内部决策文档「VOS + YYDB TypeScript 门面设计」§1.1。
+ */
+export { v } from '@voml/vos';
+export type { VBuiltinName, VItemName, VWrapperName } from '@voml/vos';
+export type { AnyTypeDescriptor, Attribute, BuiltinKind, FieldDescriptor, Infer, RefDescriptor, ReferenceTarget, ScalarKind, TypeDescriptor, WrapperKind, } from '@voml/vos';
+export type { ClassDescriptor, FieldAccess, FieldMap, ItemKind, ItemMetadataKey, NamedFieldMap, NamedItemDescriptor, NamedItemKind, ObjectDescriptor, RowOf, StructuralDescriptor, TableDescriptor, } from '@voml/vos';
+export type { ReferenceKey, VosFileRef } from '@voml/vos';

package/dist/shared/vos.js

@@ -0,0 +1,15 @@
+/**
+ * `@yydb/yydb` 对 `@voml/vos` 的 re-export 门。
+ *
+ * 普通 YYDB 用户只依赖 `@yydb/yydb`，不必再显式安装或引入 `@voml/vos`。
+ * 这里只转发 YYDB 作者面需要的 VOS 建模面：`v` builder、descriptor 类型与 `Infer` 推导。
+ *
+ * 刻意不转发：
+ * - VOS source 发射：`@voml/vos` 不生成 `.vos` 文本（descriptor 直接编译 canonical artifact），
+ *   源码书写与格式化属于 `@voml/vos-language`。
+ * - `checkSource` / `VosDiagnostic`：VOS source 检查与语言层诊断属于 `@voml/vos-language`，
+ *   不属于 `@voml/vos` 建模面，也不进 YYDB 作者面。
+ *
+ * 依赖边界见内部决策文档「VOS + YYDB TypeScript 门面设计」§1.1。
+ */
+export { v } from '@voml/vos';

package/dist/shared/wasm-envelope.d.ts

@@ -0,0 +1,40 @@
+/** Parsed `{ ok, rows, error, code }` envelope from wasm unit-valued calls. */
+export type WasmRowsResult = {
+    ok: boolean;
+    rows: Record<string, unknown>[];
+    error: string | null;
+    code: string | null;
+};
+/** Parsed `{ ok, schema, error, code }` envelope from wasm `getSchema`. */
+export type WasmSchemaResult = {
+    ok: boolean;
+    schema: {
+        version: number;
+        document: string;
+    } | null;
+    error: string | null;
+    code: string | null;
+};
+/** Parsed `{ ok, value, error, code }` envelope from wasm `get`. */
+export type WasmKvGetResult = {
+    ok: boolean;
+    value: number[] | null;
+    error: string | null;
+    code: string | null;
+};
+/** Parsed `{ ok, value, error, code }` envelope from wasm `callScalar`. */
+export type WasmScalarResult = {
+    ok: boolean;
+    value: string | number | boolean | null;
+    error: string | null;
+    code: string | null;
+};
+export type WireScalarValue = string | number | boolean | null;
+export type SchemaVersion = {
+    version: number;
+    document: string;
+};
+export declare function parseWasmUnitResult(payload: string, operation: string): void;
+export declare function parseWasmSchemaResult(payload: string, operation: string): SchemaVersion | null;
+export declare function parseWasmScalarResult(payload: string, operation: string): WireScalarValue;
+export declare function parseWasmKvGetResult(payload: string, operation: string): Uint8Array | null;

package/dist/shared/wasm-envelope.js

@@ -0,0 +1,49 @@
+import { YydbError, YydbErrorCodes } from '@yydb/yydb-client';
+function parseJson(payload, operation) {
+    try {
+        return JSON.parse(payload);
+    }
+    catch (cause) {
+        throw new YydbError(YydbErrorCodes.clientDecodeFailure, `${operation}: invalid JSON envelope`, { operation, cause });
+    }
+}
+/**
+ * Build the error for a failed wasm envelope. The Rust core always sends a
+ * stable `code`; a missing one means the wasm artifact is stale, which is a
+ * decode failure rather than an engine failure.
+ */
+function envelopeError(envelope, operation) {
+    const code = envelope.code ?? YydbErrorCodes.clientDecodeFailure;
+    const message = envelope.error ?? `${operation}: wasm envelope carried no message`;
+    return new YydbError(code, message, { operation });
+}
+export function parseWasmUnitResult(payload, operation) {
+    const parsed = parseJson(payload, operation);
+    if (!parsed.ok) {
+        throw envelopeError(parsed, operation);
+    }
+}
+export function parseWasmSchemaResult(payload, operation) {
+    const parsed = parseJson(payload, operation);
+    if (!parsed.ok) {
+        throw envelopeError(parsed, operation);
+    }
+    return parsed.schema;
+}
+export function parseWasmScalarResult(payload, operation) {
+    const parsed = parseJson(payload, operation);
+    if (!parsed.ok) {
+        throw envelopeError(parsed, operation);
+    }
+    return parsed.value;
+}
+export function parseWasmKvGetResult(payload, operation) {
+    const parsed = parseJson(payload, operation);
+    if (!parsed.ok) {
+        throw envelopeError(parsed, operation);
+    }
+    if (parsed.value === null) {
+        return null;
+    }
+    return Uint8Array.from(parsed.value);
+}

package/dist/wasm/binding.d.ts

@@ -0,0 +1 @@
+export { checkSchema, createMemorySession, initWasm, introspectSchema, openPersistentSession, resetWasmBindingForTests, yydbVersion, type CheckSchemaResult, type InitWasmOptions, type WasmInitInput, type WasmSession, } from '@yydb/yydb-unknown-wasm32';

package/dist/wasm/binding.js

@@ -0,0 +1 @@
+export { checkSchema, createMemorySession, initWasm, introspectSchema, openPersistentSession, resetWasmBindingForTests, yydbVersion, } from '@yydb/yydb-unknown-wasm32';

package/dist/wasm/database.d.ts

@@ -0,0 +1,50 @@
+import { defineMicro as buildMicro, type DefinedMicro, type MicroHandle } from '../shared/micro.js';
+import type { UdfScalarDescriptor } from '../shared/udf-types.js';
+import { type SchemaVersion } from '../shared/wasm-envelope.js';
+import { type CheckSchemaResult, type InitWasmOptions } from './binding.js';
+export type WasmOpenOptions = InitWasmOptions;
+/**
+ * Browser-facing YYDB handle backed by an in-process wasm session.
+ * Use `open` for OPFS-backed paths and `openInMemory` for ephemeral state.
+ */
+export declare class Database {
+    readonly path: string;
+    private session;
+    private readonly kind;
+    private readonly microRegistry;
+    private constructor();
+    /** Open an OPFS-backed database at `path` (for example `app.yydb`). */
+    static open(path: string, options?: WasmOpenOptions): Promise<Database>;
+    /** Open a stateful in-memory database session. */
+    static openInMemory(options?: WasmOpenOptions): Promise<Database>;
+    /** Library version from the wasm binding. */
+    version(): string;
+    /** Engine version string (Node API parity). */
+    serverVersion(): Promise<string>;
+    /** Database info text (`path=…\\n…`), matching the YY wire `Info` reply. */
+    info(): Promise<string>;
+    /** Parse and validate a VOS schema document without opening a session. */
+    checkSchema(source: string): CheckSchemaResult;
+    /** Persist schema document. `version` is accepted for Node API parity; wasm uses the document body. */
+    ensureSchema(_version: number, document: string): Promise<void>;
+    getSchema(): Promise<SchemaVersion | null>;
+    get(key: string): Promise<Uint8Array | null>;
+    put(key: string, value: Uint8Array | string): Promise<void>;
+    /**
+     * Build a typed session-local micro definition. Does not register it with
+     * the engine until `registerMicro` is called.
+     */
+    defineMicro<TArgs extends readonly UdfScalarDescriptor[], TReturn extends UdfScalarDescriptor>(definition: Parameters<typeof buildMicro<TArgs, TReturn>>[0]): DefinedMicro<TArgs, TReturn>;
+    /**
+     * Install a `defineMicro` definition into the current session registry and
+     * sync metadata to the embedded engine. Host micros are session-local.
+     */
+    registerMicro<TArgs extends readonly UdfScalarDescriptor[], TReturn extends UdfScalarDescriptor>(definition: DefinedMicro<TArgs, TReturn>): Promise<MicroHandle>;
+    /** Invoke a registered scalar UDF on the embedded engine. */
+    callScalar(name: string, version: number, args: readonly (string | number | boolean | null)[]): Promise<string | number | boolean | null>;
+    /** Whether this handle owns a persistent OPFS session. */
+    isPersistent(): boolean;
+    /** Close the embedded session. Idempotent; further calls fail with `yydb.session.closed`. */
+    close(): Promise<void>;
+    private requireSession;
+}

package/dist/wasm/database.js

@@ -0,0 +1,110 @@
+import { encodeMicroRegister, encodeScalarCall, YydbError, YydbErrorCodes } from '@yydb/yydb-client';
+import { defineMicro as buildMicro, microFingerprint, udfWireKind, MicroSessionRegistry, } from '../shared/micro.js';
+import { parseWasmKvGetResult, parseWasmScalarResult, parseWasmSchemaResult, parseWasmUnitResult, } from '../shared/wasm-envelope.js';
+import { checkSchema, createMemorySession, initWasm, openPersistentSession, yydbVersion, } from './binding.js';
+/**
+ * Browser-facing YYDB handle backed by an in-process wasm session.
+ * Use `open` for OPFS-backed paths and `openInMemory` for ephemeral state.
+ */
+export class Database {
+    path;
+    session;
+    kind;
+    microRegistry;
+    constructor(kind, path, session) {
+        this.kind = kind;
+        this.path = path;
+        this.session = session;
+        this.microRegistry = new MicroSessionRegistry();
+        session.setMicroHostInvoker((payload) => this.microRegistry.invokeFromWire(payload));
+    }
+    /** Open an OPFS-backed database at `path` (for example `app.yydb`). */
+    static async open(path, options = {}) {
+        await initWasm(options);
+        const session = openPersistentSession(path);
+        return new Database('persistent', session.path ?? path, session);
+    }
+    /** Open a stateful in-memory database session. */
+    static async openInMemory(options = {}) {
+        await initWasm(options);
+        const session = createMemorySession();
+        return new Database('memory', ':memory:', session);
+    }
+    /** Library version from the wasm binding. */
+    version() {
+        return yydbVersion();
+    }
+    /** Engine version string (Node API parity). */
+    async serverVersion() {
+        return yydbVersion();
+    }
+    /** Database info text (`path=…\\n…`), matching the YY wire `Info` reply. */
+    async info() {
+        return this.requireSession('info').info();
+    }
+    /** Parse and validate a VOS schema document without opening a session. */
+    checkSchema(source) {
+        return checkSchema(source);
+    }
+    /** Persist schema document. `version` is accepted for Node API parity; wasm uses the document body. */
+    async ensureSchema(_version, document) {
+        parseWasmUnitResult(this.requireSession('schemaEnsure').ensureSchema(document), 'schemaEnsure');
+    }
+    async getSchema() {
+        return parseWasmSchemaResult(this.requireSession('schemaGet').getSchema(), 'schemaGet');
+    }
+    async get(key) {
+        return parseWasmKvGetResult(this.requireSession('kvGet').get(key), 'kvGet');
+    }
+    async put(key, value) {
+        const bytes = typeof value === 'string' ? new TextEncoder().encode(value) : value;
+        parseWasmUnitResult(this.requireSession('kvPut').put(key, bytes), 'kvPut');
+    }
+    /**
+     * Build a typed session-local micro definition. Does not register it with
+     * the engine until `registerMicro` is called.
+     */
+    defineMicro(definition) {
+        return buildMicro(definition);
+    }
+    /**
+     * Install a `defineMicro` definition into the current session registry and
+     * sync metadata to the embedded engine. Host micros are session-local.
+     */
+    async registerMicro(definition) {
+        const handle = this.microRegistry.register(definition);
+        const body = encodeMicroRegister({
+            hostId: handle.hostId,
+            handleVersion: handle.implementationVersion,
+            udfVersion: definition.version,
+            name: definition.name,
+            functionId: handle.functionId,
+            args: definition.args.map(udfWireKind),
+            returns: udfWireKind(definition.returns),
+            fingerprint: microFingerprint(definition.name, definition.version),
+        });
+        parseWasmUnitResult(this.requireSession('microRegister').registerMicro(body), 'microRegister');
+        return handle;
+    }
+    /** Invoke a registered scalar UDF on the embedded engine. */
+    async callScalar(name, version, args) {
+        const body = encodeScalarCall(name, version, args);
+        return parseWasmScalarResult(this.requireSession('callScalar').callScalar(body), 'callScalar');
+    }
+    /** Whether this handle owns a persistent OPFS session. */
+    isPersistent() {
+        return this.kind === 'persistent';
+    }
+    /** Close the embedded session. Idempotent; further calls fail with `yydb.session.closed`. */
+    async close() {
+        const session = this.session;
+        this.session = null;
+        session?.close();
+    }
+    requireSession(operation) {
+        if (!this.session) {
+            throw new YydbError(YydbErrorCodes.sessionClosed, `${operation}: @yydb/yydb/wasm session is closed`, { operation });
+        }
+        return this.session;
+    }
+}

package/dist/wasm/index.d.ts

@@ -0,0 +1,8 @@
+export { Database, type WasmOpenOptions } from './database.js';
+export { YydbError, YydbErrorCodes, isRetryableYydbCode, isYydbError } from '@yydb/yydb-client';
+export type { YydbErrorCode, YydbErrorOptions } from '@yydb/yydb-client';
+export { checkSchema, createMemorySession, initWasm, introspectSchema, openPersistentSession, resetWasmBindingForTests, yydbVersion, type CheckSchemaResult, type InitWasmOptions, type WasmInitInput, type WasmSession, } from './binding.js';
+export { defineMicro, type DefinedMicro, type MicroHandle, type TsMicroDefinitionInput, MicroSessionRegistry } from '../shared/micro.js';
+export { type InferUdfArgs, type InferUdfReturn, type MicroEffect, type MicroInvocationMode, type UdfScalarDescriptor, type UdfScalarKind, } from '../shared/udf-types.js';
+export type { SchemaVersion } from '../shared/wasm-envelope.js';
+export * from '../shared/vos.js';

package/dist/wasm/index.js

@@ -0,0 +1,5 @@
+export { Database } from './database.js';
+export { YydbError, YydbErrorCodes, isRetryableYydbCode, isYydbError } from '@yydb/yydb-client';
+export { checkSchema, createMemorySession, initWasm, introspectSchema, openPersistentSession, resetWasmBindingForTests, yydbVersion, } from './binding.js';
+export { defineMicro, MicroSessionRegistry } from '../shared/micro.js';
+export * from '../shared/vos.js';

package/package.json

@@ -1,22 +1,31 @@
 {
   "name": "@yydb/yydb",
-  "version": "0.0.4",
-  "description": "YYDB all-in-one for Node: embedded engine, CLI, and local serve",
+  "version": "0.0.6",
+  "description": "YYDB all-in-one: Node embedded engine and CLI, browser wasm core",
   "license": "MPL-2.0",
   "type": "module",
   "bin": {
-    "yydb": "./dist/cli.js"
+    "yydb": "./dist/node/cli.js"
   },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "main": "./dist/node/index.js",
+  "types": "./dist/node/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "types": "./dist/node/index.d.ts",
+      "node": "./dist/node/index.js",
+      "default": "./dist/wasm/index.js"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "import": "./dist/node/index.js"
+    },
+    "./wasm": {
+      "types": "./dist/wasm/index.d.ts",
+      "import": "./dist/wasm/index.js"
     },
     "./cli": {
-      "types": "./dist/cli.d.ts",
-      "import": "./dist/cli.js"
+      "types": "./dist/node/cli.d.ts",
+      "import": "./dist/node/cli.js"
     }
   },
   "files": [
@@ -24,8 +33,8 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "pnpm run build && node --experimental-strip-types --test src/**/*.test.ts"
+    "build": "tsc -p tsconfig.node.json && tsc -p tsconfig.wasm.json",
+    "test": "pnpm run build && node --experimental-strip-types --test src/node/**/*.test.ts src/shared/**/*.test.ts"
   },
   "repository": {
     "type": "git",
@@ -48,7 +57,9 @@
   },
   "dependencies": {
     "@vmz/commander": "^0.2.0",
-    "@yydb/yydb-client": "0.0.4"
+    "@voml/vos": "^0.0.1",
+    "@yydb/yydb-client": "0.0.6",
+    "@yydb/yydb-unknown-wasm32": "0.0.6"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",
@@ -58,9 +69,9 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@yydb/yydb-win32-x64": "0.0.4",
-    "@yydb/yydb-linux-x64": "0.0.4",
-    "@yydb/yydb-darwin-x64": "0.0.4",
-    "@yydb/yydb-darwin-arm64": "0.0.4"
+    "@yydb/yydb-win32-x64": "0.0.6",
+    "@yydb/yydb-linux-x64": "0.0.6",
+    "@yydb/yydb-darwin-x64": "0.0.6",
+    "@yydb/yydb-darwin-arm64": "0.0.6"
   }
 }

package/dist/index.d.ts

@@ -1,4 +0,0 @@
-export { Database, type OpenOptions } from './database.js';
-export { defineMicro, type DefinedMicro, type MicroHandle, type TsMicroDefinitionInput, MicroSessionRegistry } from './micro.js';
-export { bool, i64, nullType, text, type InferUdfArgs, type InferUdfReturn, type MicroEffect, type MicroInvocationMode, type UdfScalarKind, type UdfTypeDescriptor, } from './udf-types.js';
-export { nativeBindingName, platformKey, resolveYydbBinary, resolveYydbCli } from './resolve-bin.js';

package/dist/index.js

@@ -1,4 +0,0 @@
-export { Database } from './database.js';
-export { defineMicro, MicroSessionRegistry } from './micro.js';
-export { bool, i64, nullType, text, } from './udf-types.js';
-export { nativeBindingName, platformKey, resolveYydbBinary, resolveYydbCli } from './resolve-bin.js';

package/dist/udf-types.d.ts

@@ -1,26 +0,0 @@
-/** Phase-1 scalar UDF wire kinds aligned with `yydb-udf`. */
-export type UdfScalarKind = 'i64' | 'bool' | 'text' | 'null';
-/** Runtime type descriptor used in `defineMicro` contracts. */
-export interface UdfTypeDescriptor<T = unknown> {
-    readonly kind: UdfScalarKind;
-    /** Phantom type for author-side inference only. */
-    readonly _type?: T;
-}
-/** `i64` argument or return descriptor. */
-export declare function i64(): UdfTypeDescriptor<number>;
-/** `bool` argument or return descriptor. */
-export declare function bool(): UdfTypeDescriptor<boolean>;
-/** `text` argument or return descriptor. */
-export declare function text(): UdfTypeDescriptor<string>;
-/** `null` return descriptor. */
-export declare function nullType(): UdfTypeDescriptor<null>;
-/** Maps descriptor tuple types to positional argument types. */
-export type InferUdfArgs<T extends readonly UdfTypeDescriptor[]> = {
-    [K in keyof T]: T[K] extends UdfTypeDescriptor<infer V> ? V : never;
-};
-/** Maps a return descriptor to its value type. */
-export type InferUdfReturn<T extends UdfTypeDescriptor> = T extends UdfTypeDescriptor<infer V> ? V : never;
-/** Session micro effect surface (Phase 1: pure only). */
-export type MicroEffect = 'pure';
-/** Invocation mode stored with the definition for future batch host calls. */
-export type MicroInvocationMode = 'scalar' | 'batch';

package/dist/udf-types.js

@@ -1,16 +0,0 @@
-/** `i64` argument or return descriptor. */
-export function i64() {
-    return { kind: 'i64' };
-}
-/** `bool` argument or return descriptor. */
-export function bool() {
-    return { kind: 'bool' };
-}
-/** `text` argument or return descriptor. */
-export function text() {
-    return { kind: 'text' };
-}
-/** `null` return descriptor. */
-export function nullType() {
-    return { kind: 'null' };
-}