@yydb/yydb 0.0.5 → 0.0.7

package/README.md

@@ -1,8 +1,8 @@
 # `@yydb/yydb`
 
 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,
-schema, and VOS `query` / `execute` on memory or OPFS paths.
+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).
@@ -23,7 +23,7 @@ For a wire client only (renderer or an app that already runs `yydb serve`), use
 Node.js 18+. Platform `.node` bindings install via optional dependencies.
 
 Schema truth lives in the `.yydb` file via `ensureSchema` and VOS documents. Wasm sessions mirror KV and schema calls
-and add VOS pipelines directly on the embedded core.
+on the embedded core.
 
 ## Node example
 
@@ -85,8 +85,6 @@ await db.info();
 await db.serverVersion();
 await db.registerMicro(microDefinition);
 await db.callScalar('double', 1, [21]);
-db.query('User.filter(x => x.active).collect()');
-db.execute('User { name: "Ada" }.insert()');
 db.close();
 ```
 

package/dist/node/database.d.ts

@@ -1,5 +1,5 @@
 import { defineMicro as buildMicro, type DefinedMicro, type MicroHandle } from '../shared/micro.js';
-import type { UdfTypeDescriptor } from '../shared/udf-types.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/node/database.js

@@ -3,7 +3,7 @@ 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, microFingerprint, MicroSessionRegistry } from '../shared/micro.js';
+import { defineMicro as buildMicro, microFingerprint, udfWireKind, MicroSessionRegistry, } from '../shared/micro.js';
 import { resolveYydbCli } from './resolve-bin.js';
 async function freeLoopbackPort() {
     return await new Promise((resolve, reject) => {
@@ -141,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

@@ -1,4 +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 { bool, i64, nullType, text, type InferUdfArgs, type InferUdfReturn, type MicroEffect, type MicroInvocationMode, type UdfScalarKind, type UdfTypeDescriptor, } from '../shared/udf-types.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

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

package/dist/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,14 +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/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,
@@ -111,59 +143,51 @@ export function microFingerprint(name, version) {
 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');
-            }
-            break;
-        case 'null':
-            if (value !== null) {
-                throw new Error('micro return expects null');
+                throw new Error(`${label} expects VOS \`utf8\` (a string)`);
             }
             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

@@ -1,25 +1,33 @@
-/** Phase-1 scalar UDF wire kinds aligned with `yydb-udf`. */
+/**
+ * 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';
-/** 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;
+/**
+ * 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 value type. */
-export type InferUdfReturn<T extends UdfTypeDescriptor> = T extends UdfTypeDescriptor<infer V> ? V : never;
+/** 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. */

package/dist/shared/udf-types.js

@@ -1,16 +1,14 @@
-/** `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' };
-}
+/**
+ * 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

@@ -1,10 +1,11 @@
-/** Parsed `{ ok, rows, error }` envelope from wasm VOS calls. */
+/** 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 }` envelope from wasm `getSchema`. */
+/** Parsed `{ ok, schema, error, code }` envelope from wasm `getSchema`. */
 export type WasmSchemaResult = {
     ok: boolean;
     schema: {
@@ -12,26 +13,28 @@ export type WasmSchemaResult = {
         document: string;
     } | null;
     error: string | null;
+    code: string | null;
 };
-/** Parsed `{ ok, value, error }` envelope from wasm `get`. */
+/** 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 }` envelope from wasm `callScalar`. */
+/** 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 parseWasmRowsResult(payload: string): WasmRowsResult;
-export declare function parseWasmUnitResult(payload: string): void;
-export declare function parseWasmSchemaResult(payload: string): SchemaVersion | null;
-export declare function parseWasmScalarResult(payload: string): WireScalarValue;
-export declare function parseWasmKvGetResult(payload: string): Uint8Array | null;
+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

@@ -1,43 +1,46 @@
-function parseJson(payload, label) {
+import { YydbError, YydbErrorCodes } from '@yydb/yydb-client';
+function parseJson(payload, operation) {
     try {
         return JSON.parse(payload);
     }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`${label}: invalid JSON (${message})`);
+    catch (cause) {
+        throw new YydbError(YydbErrorCodes.clientDecodeFailure, `${operation}: invalid JSON envelope`, { operation, cause });
     }
 }
-export function parseWasmRowsResult(payload) {
-    const parsed = parseJson(payload, 'wasm query/execute');
-    if (!parsed.ok) {
-        throw new Error(parsed.error ?? 'wasm query/execute failed');
-    }
-    return parsed;
+/**
+ * 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) {
-    const parsed = parseJson(payload, 'wasm unit call');
+export function parseWasmUnitResult(payload, operation) {
+    const parsed = parseJson(payload, operation);
     if (!parsed.ok) {
-        throw new Error(parsed.error ?? 'wasm unit call failed');
+        throw envelopeError(parsed, operation);
     }
 }
-export function parseWasmSchemaResult(payload) {
-    const parsed = parseJson(payload, 'wasm getSchema');
+export function parseWasmSchemaResult(payload, operation) {
+    const parsed = parseJson(payload, operation);
     if (!parsed.ok) {
-        throw new Error(parsed.error ?? 'wasm getSchema failed');
+        throw envelopeError(parsed, operation);
     }
     return parsed.schema;
 }
-export function parseWasmScalarResult(payload) {
-    const parsed = parseJson(payload, 'wasm callScalar');
+export function parseWasmScalarResult(payload, operation) {
+    const parsed = parseJson(payload, operation);
     if (!parsed.ok) {
-        throw new Error(parsed.error ?? 'wasm callScalar failed');
+        throw envelopeError(parsed, operation);
     }
     return parsed.value;
 }
-export function parseWasmKvGetResult(payload) {
-    const parsed = parseJson(payload, 'wasm get');
+export function parseWasmKvGetResult(payload, operation) {
+    const parsed = parseJson(payload, operation);
     if (!parsed.ok) {
-        throw new Error(parsed.error ?? 'wasm get failed');
+        throw envelopeError(parsed, operation);
     }
     if (parsed.value === null) {
         return null;

package/dist/wasm/binding.d.ts

@@ -1 +1 @@
-export { checkSchema, createMemorySession, initWasm, introspectSchema, openPersistentSession, queryMemory, resetWasmBindingForTests, yydbVersion, type CheckSchemaResult, type InitWasmOptions, type WasmInitInput, type WasmSession, } from '@yydb/yydb-unknown-wasm32';
+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

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

package/dist/wasm/database.d.ts

@@ -1,5 +1,5 @@
 import { defineMicro as buildMicro, type DefinedMicro, type MicroHandle } from '../shared/micro.js';
-import type { UdfTypeDescriptor } from '../shared/udf-types.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;
@@ -30,24 +30,21 @@ export declare class Database {
     getSchema(): Promise<SchemaVersion | null>;
     get(key: string): Promise<Uint8Array | null>;
     put(key: string, value: Uint8Array | string): Promise<void>;
-    /** VOS read pipeline (for example `User.filter(x => x.active).collect()`). */
-    query(source: string): Record<string, unknown>[];
-    /** Unit-valued VOS write programs (for example `User { … }.insert()`). */
-    execute(source: string): void;
     /**
      * Build a typed session-local micro definition. Does not register it with
      * the engine until `registerMicro` 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` definition into the current session registry and
      * sync metadata to the embedded engine. Host micros are session-local.
      */
-    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 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(): void;
+    /** Close the embedded session. Idempotent; further calls fail with `yydb.session.closed`. */
+    close(): Promise<void>;
     private requireSession;
 }

package/dist/wasm/database.js

@@ -1,6 +1,6 @@
-import { encodeMicroRegister, encodeScalarCall } from '@yydb/yydb-client';
-import { defineMicro as buildMicro, microFingerprint, MicroSessionRegistry } from '../shared/micro.js';
-import { parseWasmKvGetResult, parseWasmRowsResult, parseWasmScalarResult, parseWasmSchemaResult, parseWasmUnitResult, } from '../shared/wasm-envelope.js';
+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.
@@ -40,7 +40,7 @@ export class Database {
     }
     /** Database info text (`path=…\\n…`), matching the YY wire `Info` reply. */
     async info() {
-        return this.requireSession().info();
+        return this.requireSession('info').info();
     }
     /** Parse and validate a VOS schema document without opening a session. */
     checkSchema(source) {
@@ -48,25 +48,17 @@ export class Database {
     }
     /** Persist schema document. `version` is accepted for Node API parity; wasm uses the document body. */
     async ensureSchema(_version, document) {
-        parseWasmUnitResult(this.requireSession().ensureSchema(document));
+        parseWasmUnitResult(this.requireSession('schemaEnsure').ensureSchema(document), 'schemaEnsure');
     }
     async getSchema() {
-        return parseWasmSchemaResult(this.requireSession().getSchema());
+        return parseWasmSchemaResult(this.requireSession('schemaGet').getSchema(), 'schemaGet');
     }
     async get(key) {
-        return parseWasmKvGetResult(this.requireSession().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().put(key, bytes));
-    }
-    /** VOS read pipeline (for example `User.filter(x => x.active).collect()`). */
-    query(source) {
-        return parseWasmRowsResult(this.requireSession().query(source)).rows;
-    }
-    /** Unit-valued VOS write programs (for example `User { … }.insert()`). */
-    execute(source) {
-        parseWasmUnitResult(this.requireSession().execute(source));
+        parseWasmUnitResult(this.requireSession('kvPut').put(key, bytes), 'kvPut');
     }
     /**
      * Build a typed session-local micro definition. Does not register it with
@@ -87,29 +79,31 @@ 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),
         });
-        parseWasmUnitResult(this.requireSession().registerMicro(body));
+        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(body));
+        return parseWasmScalarResult(this.requireSession('callScalar').callScalar(body), 'callScalar');
     }
     /** Whether this handle owns a persistent OPFS session. */
     isPersistent() {
         return this.kind === 'persistent';
     }
-    close() {
-        this.session?.close();
+    /** Close the embedded session. Idempotent; further calls fail with `yydb.session.closed`. */
+    async close() {
+        const session = this.session;
         this.session = null;
+        session?.close();
     }
-    requireSession() {
+    requireSession(operation) {
         if (!this.session) {
-            throw new Error('@yydb/yydb/wasm: database session is closed');
+            throw new YydbError(YydbErrorCodes.sessionClosed, `${operation}: @yydb/yydb/wasm session is closed`, { operation });
         }
         return this.session;
     }

package/dist/wasm/index.d.ts

@@ -1,5 +1,8 @@
 export { Database, type WasmOpenOptions } from './database.js';
-export { checkSchema, createMemorySession, initWasm, introspectSchema, openPersistentSession, queryMemory, resetWasmBindingForTests, yydbVersion, type CheckSchemaResult, type InitWasmOptions, type WasmInitInput, type WasmSession, } from './binding.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 { bool, i64, nullType, text, type InferUdfArgs, type InferUdfReturn, type MicroEffect, type MicroInvocationMode, type UdfScalarKind, type UdfTypeDescriptor, } from '../shared/udf-types.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

@@ -1,4 +1,5 @@
 export { Database } from './database.js';
-export { checkSchema, createMemorySession, initWasm, introspectSchema, openPersistentSession, queryMemory, resetWasmBindingForTests, yydbVersion, } from './binding.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 { bool, i64, nullType, text, } from '../shared/udf-types.js';
+export * from '../shared/vos.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yydb/yydb",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "YYDB all-in-one: Node embedded engine and CLI, browser wasm core",
   "license": "MPL-2.0",
   "type": "module",
@@ -57,8 +57,9 @@
   },
   "dependencies": {
     "@vmz/commander": "^0.2.0",
-    "@yydb/yydb-client": "0.0.5",
-    "@yydb/yydb-unknown-wasm32": "0.0.5"
+    "@voml/vos": "^0.0.1",
+    "@yydb/yydb-client": "0.0.7",
+    "@yydb/yydb-unknown-wasm32": "0.0.7"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",
@@ -68,9 +69,9 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@yydb/yydb-win32-x64": "0.0.5",
-    "@yydb/yydb-linux-x64": "0.0.5",
-    "@yydb/yydb-darwin-x64": "0.0.5",
-    "@yydb/yydb-darwin-arm64": "0.0.5"
+    "@yydb/yydb-win32-x64": "0.0.7",
+    "@yydb/yydb-linux-x64": "0.0.7",
+    "@yydb/yydb-darwin-x64": "0.0.7",
+    "@yydb/yydb-darwin-arm64": "0.0.7"
   }
 }