@yydb/yydb 0.0.12 → 0.0.15

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/node/native.d.ts

@@ -0,0 +1,9 @@
+export interface YydbNative {
+    version(): string;
+    serve(dbPath: string, bind: string, insecureBind?: boolean): void;
+    initDb(dbPath: string, schemaVersion: number, schemaDocument?: string | null): void;
+    infoText(dbPath: string): string;
+    readSchemaFile(schemaPath: string): string;
+}
+/** Load the platform native binding used by the `yydb` CLI. */
+export declare function loadNative(): YydbNative;

package/dist/node/native.js

@@ -0,0 +1,32 @@
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { platformKey } from './resolve-bin.js';
+function loadModule(specifier) {
+    const require = createRequire(import.meta.url);
+    const loaded = require(specifier);
+    return (loaded.default ?? loaded);
+}
+/** Load the platform native binding used by the `yydb` CLI. */
+export function loadNative() {
+    const fromEnv = process.env.YYDB_NATIVE?.trim();
+    if (fromEnv) {
+        const bindingPath = path.resolve(fromEnv);
+        if (!fs.existsSync(bindingPath)) {
+            throw new Error(`YYDB_NATIVE points to missing binding: ${fromEnv}`);
+        }
+        return loadModule(bindingPath);
+    }
+    const key = platformKey();
+    if (!key) {
+        throw new Error(`YYDB native binding not available for ${process.platform}-${process.arch}`);
+    }
+    const pkg = `@yydb/yydb-${key}`;
+    try {
+        return loadModule(pkg);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`YYDB native binding not found. Reinstall @yydb/yydb with optional dependencies, set YYDB_NATIVE, or stage ${pkg}. ${message}`);
+    }
+}

package/dist/node/resolve-bin.d.ts

@@ -0,0 +1,15 @@
+/// <reference types="node" />
+export type PlatformKey = 'win32-x64' | 'linux-x64' | 'darwin-x64' | 'darwin-arm64';
+/** Map Node platform/arch to optionalDependency package suffix. */
+export declare function platformKey(platform?: NodeJS.Platform, arch?: NodeJS.Architecture): PlatformKey | null;
+/** Native binding filename inside each `@yydb/yydb-<platform>` package `lib/`. */
+export declare function nativeBindingName(key: PlatformKey): string;
+/**
+ * Resolve the TypeScript `yydb` CLI entry script.
+ * Order: `YYDB_CLI` → this package `dist/cli.js`.
+ */
+export declare function resolveYydbCli(): string;
+/**
+ * @deprecated Use {@link resolveYydbCli}. Kept for callers that still import this name.
+ */
+export declare function resolveYydbBinary(): string;

package/dist/node/resolve-bin.js

@@ -0,0 +1,62 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Map Node platform/arch to optionalDependency package suffix. */
+export function platformKey(platform = process.platform, arch = process.arch) {
+    if (platform === 'win32' && arch === 'x64')
+        return 'win32-x64';
+    if (platform === 'linux' && arch === 'x64')
+        return 'linux-x64';
+    if (platform === 'darwin' && arch === 'x64')
+        return 'darwin-x64';
+    if (platform === 'darwin' && arch === 'arm64')
+        return 'darwin-arm64';
+    return null;
+}
+/** Native binding filename inside each `@yydb/yydb-<platform>` package `lib/`. */
+export function nativeBindingName(key) {
+    switch (key) {
+        case 'win32-x64':
+            return 'yydb-win32-x64-msvc.node';
+        case 'linux-x64':
+            return 'yydb-linux-x64-gnu.node';
+        case 'darwin-x64':
+            return 'yydb-darwin-x64.node';
+        case 'darwin-arm64':
+            return 'yydb-darwin-arm64.node';
+    }
+}
+function existsFile(filePath) {
+    try {
+        fs.accessSync(filePath, fs.constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the TypeScript `yydb` CLI entry script.
+ * Order: `YYDB_CLI` → this package `dist/cli.js`.
+ */
+export function resolveYydbCli() {
+    const fromEnv = process.env.YYDB_CLI?.trim();
+    if (fromEnv) {
+        if (!existsFile(fromEnv)) {
+            throw new Error(`YYDB_CLI points to missing script: ${fromEnv}`);
+        }
+        return path.resolve(fromEnv);
+    }
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const candidate = path.join(here, 'cli.js');
+    if (!existsFile(candidate)) {
+        throw new Error('YYDB CLI script not found. Build `@yydb/yydb` (`pnpm --filter @yydb/yydb build`) or set YYDB_CLI.');
+    }
+    return candidate;
+}
+/**
+ * @deprecated Use {@link resolveYydbCli}. Kept for callers that still import this name.
+ */
+export function resolveYydbBinary() {
+    return resolveYydbCli();
+}

package/dist/resolve-bin.d.ts

@@ -0,0 +1,15 @@
+/// <reference types="node" />
+export type PlatformKey = 'win32-x64' | 'linux-x64' | 'darwin-x64' | 'darwin-arm64';
+/** Map Node platform/arch to optionalDependency package suffix. */
+export declare function platformKey(platform?: NodeJS.Platform, arch?: NodeJS.Architecture): PlatformKey | null;
+/** Native binding filename inside each `@yydb/yydb-<platform>` package `lib/`. */
+export declare function nativeBindingName(key: PlatformKey): string;
+/**
+ * Resolve the TypeScript `yydb` CLI entry script.
+ * Order: `YYDB_CLI` → this package `dist/cli.js`.
+ */
+export declare function resolveYydbCli(): string;
+/**
+ * @deprecated Use {@link resolveYydbCli}. Kept for callers that still import this name.
+ */
+export declare function resolveYydbBinary(): string;

package/dist/resolve-bin.js

@@ -0,0 +1,62 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Map Node platform/arch to optionalDependency package suffix. */
+export function platformKey(platform = process.platform, arch = process.arch) {
+    if (platform === 'win32' && arch === 'x64')
+        return 'win32-x64';
+    if (platform === 'linux' && arch === 'x64')
+        return 'linux-x64';
+    if (platform === 'darwin' && arch === 'x64')
+        return 'darwin-x64';
+    if (platform === 'darwin' && arch === 'arm64')
+        return 'darwin-arm64';
+    return null;
+}
+/** Native binding filename inside each `@yydb/yydb-<platform>` package `lib/`. */
+export function nativeBindingName(key) {
+    switch (key) {
+        case 'win32-x64':
+            return 'yydb-win32-x64-msvc.node';
+        case 'linux-x64':
+            return 'yydb-linux-x64-gnu.node';
+        case 'darwin-x64':
+            return 'yydb-darwin-x64.node';
+        case 'darwin-arm64':
+            return 'yydb-darwin-arm64.node';
+    }
+}
+function existsFile(filePath) {
+    try {
+        fs.accessSync(filePath, fs.constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the TypeScript `yydb` CLI entry script.
+ * Order: `YYDB_CLI` → this package `dist/cli.js`.
+ */
+export function resolveYydbCli() {
+    const fromEnv = process.env.YYDB_CLI?.trim();
+    if (fromEnv) {
+        if (!existsFile(fromEnv)) {
+            throw new Error(`YYDB_CLI points to missing script: ${fromEnv}`);
+        }
+        return path.resolve(fromEnv);
+    }
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const candidate = path.join(here, 'cli.js');
+    if (!existsFile(candidate)) {
+        throw new Error('YYDB CLI script not found. Build `@yydb/yydb` (`pnpm --filter @yydb/yydb build`) or set YYDB_CLI.');
+    }
+    return candidate;
+}
+/**
+ * @deprecated Use {@link resolveYydbCli}. Kept for callers that still import this name.
+ */
+export function resolveYydbBinary() {
+    return resolveYydbCli();
+}

package/dist/shared/errors.d.ts

@@ -2,12 +2,57 @@
  * Host-facing YYDB error surface.
  *
  * Every public failure carries a stable `code`: engine codes come from the
- * Rust core (`yydb.schema.invalid`, …) over N-API or the wire, client codes
- * are minted locally with the `yydb.client.` prefix. Branch on `code` —
- * `message` is display text only.
+ * Rust core (`yydb.schema.invalid`, …) over N-API or the wire; client codes
+ * are minted locally with the `yydb.client.` prefix. **Branch on `code`** —
+ * `message` is display text only and must never be used for retry decisions.
+ *
+ * ## Where codes live
+ *
+ * Engine codes live in Rust (`yydb_types::Error` variants → DiagnosticEnvelope).
+ * The TS side no longer keeps a hardcoded engine-code table — when Rust gains a
+ * new variant, hosts pick up the new code string via {@link fromDiagnosticJson}
+ * without any TS change. Client codes (`yydb.client.*`) are minted only on the
+ * host side and remain available as constants below.
+ */
+/**
+ * Client-side error codes that never originate from Rust.
+ *
+ * Engine codes (`yydb.schema.*`, `yydb.udf.*`, `yydb.io`, …) are emitted by
+ * Rust and should be matched via string literals or from the diagnostic JSON
+ * envelope — they are intentionally not duplicated here.
+ */
+export declare const YydbClientErrorCodes: {
+    /** serve() endpoint is empty or invalid. */
+    readonly clientInvalidEndpoint: "yydb.client.invalid_endpoint";
+    /** connect() socket / transport layer failure. */
+    readonly clientTransportFailure: "yydb.client.transport_failure";
+    /** Server replied with a request id we did not send. */
+    readonly clientRequestIdMismatch: "yydb.client.request_id_mismatch";
+    /** Server replied with a msg_type we did not request. */
+    readonly clientUnexpectedResponse: "yydb.client.unexpected_response";
+    /** Could not parse an Error frame body from the wire. */
+    readonly clientDecodeFailure: "yydb.client.decode_failure";
+    /** The YYDB session is already closed. */
+    readonly sessionClosed: "yydb.session.closed";
+};
+/**
+ * @deprecated Engine codes moved to Rust — use string literals or match on
+ * {@link YydbError.code} returned from {@link fromDiagnosticJson}. This table
+ * exists only for transition; new engine error variants will **not** be added here.
  */
-/** Stable codes known to the TypeScript hosts. */
 export declare const YydbErrorCodes: {
+    /** serve() endpoint is empty or invalid. */
+    readonly clientInvalidEndpoint: "yydb.client.invalid_endpoint";
+    /** connect() socket / transport layer failure. */
+    readonly clientTransportFailure: "yydb.client.transport_failure";
+    /** Server replied with a request id we did not send. */
+    readonly clientRequestIdMismatch: "yydb.client.request_id_mismatch";
+    /** Server replied with a msg_type we did not request. */
+    readonly clientUnexpectedResponse: "yydb.client.unexpected_response";
+    /** Could not parse an Error frame body from the wire. */
+    readonly clientDecodeFailure: "yydb.client.decode_failure";
+    /** The YYDB session is already closed. */
+    readonly sessionClosed: "yydb.session.closed";
     readonly io: "yydb.io";
     readonly corrupt: "yydb.corrupt";
     readonly schemaConflict: "yydb.schema.conflict";
@@ -25,21 +70,23 @@ export declare const YydbErrorCodes: {
     readonly fencingMismatch: "yydb.fencing.mismatch";
     readonly leaseExpired: "yydb.lease.expired";
     readonly quotaExceeded: "yydb.quota.exceeded";
-    readonly sessionClosed: "yydb.session.closed";
-    readonly clientInvalidEndpoint: "yydb.client.invalid_endpoint";
-    readonly clientTransportFailure: "yydb.client.transport_failure";
-    readonly clientRequestIdMismatch: "yydb.client.request_id_mismatch";
-    readonly clientUnexpectedResponse: "yydb.client.unexpected_response";
-    readonly clientDecodeFailure: "yydb.client.decode_failure";
 };
-/** A known code, or any future code the engine introduces. */
-export type YydbErrorCode = (typeof YydbErrorCodes)[keyof typeof YydbErrorCodes] | (string & {});
-/** Whether `code` may be retried with the same arguments. */
-export declare function isRetryableYydbCode(code: string): boolean;
+/** Any stable YYDB error code string — engine, client, or future variant. */
+export type YydbErrorCode = string;
 /** Options carried by a {@link YydbError}. */
 export interface YydbErrorOptions {
     /** Operation that failed (`schemaGet`, `kvPut`, `query`, …). */
     operation?: string;
+    /**
+     * Whether the caller may retry with the same arguments.
+     *
+     * When omitted, constructor defaults to `false` (conservative). Callers
+     * that mint their own errors (especially client-local retryable ones like
+     * `yydb.client.transport_failure`) **must** set this explicitly. Engine
+     * errors coming through {@link fromDiagnosticJson} always carry the Rust-
+     * authoritative `retryable` value and override the default.
+     */
+    retryable?: boolean;
     /** Structured parameters for catalog templating (when present). */
     params?: Readonly<Record<string, string>>;
     /** Underlying failure when this error wraps one. */
@@ -47,7 +94,7 @@ export interface YydbErrorOptions {
 }
 /** YYDB failure with a stable machine-readable {@link YydbError.code}. */
 export declare class YydbError extends Error {
-    /** Stable code — engine code or `yydb.client.*`. */
+    /** Stable code — engine code (from Rust) or `yydb.client.*`. */
     readonly code: string;
     /** Operation that failed. */
     readonly operation: string;

package/dist/shared/errors.js

@@ -2,12 +2,46 @@
  * Host-facing YYDB error surface.
  *
  * Every public failure carries a stable `code`: engine codes come from the
- * Rust core (`yydb.schema.invalid`, …) over N-API or the wire, client codes
- * are minted locally with the `yydb.client.` prefix. Branch on `code` —
- * `message` is display text only.
+ * Rust core (`yydb.schema.invalid`, …) over N-API or the wire; client codes
+ * are minted locally with the `yydb.client.` prefix. **Branch on `code`** —
+ * `message` is display text only and must never be used for retry decisions.
+ *
+ * ## Where codes live
+ *
+ * Engine codes live in Rust (`yydb_types::Error` variants → DiagnosticEnvelope).
+ * The TS side no longer keeps a hardcoded engine-code table — when Rust gains a
+ * new variant, hosts pick up the new code string via {@link fromDiagnosticJson}
+ * without any TS change. Client codes (`yydb.client.*`) are minted only on the
+ * host side and remain available as constants below.
+ */
+/**
+ * Client-side error codes that never originate from Rust.
+ *
+ * Engine codes (`yydb.schema.*`, `yydb.udf.*`, `yydb.io`, …) are emitted by
+ * Rust and should be matched via string literals or from the diagnostic JSON
+ * envelope — they are intentionally not duplicated here.
+ */
+export const YydbClientErrorCodes = {
+    /** serve() endpoint is empty or invalid. */
+    clientInvalidEndpoint: 'yydb.client.invalid_endpoint',
+    /** connect() socket / transport layer failure. */
+    clientTransportFailure: 'yydb.client.transport_failure',
+    /** Server replied with a request id we did not send. */
+    clientRequestIdMismatch: 'yydb.client.request_id_mismatch',
+    /** Server replied with a msg_type we did not request. */
+    clientUnexpectedResponse: 'yydb.client.unexpected_response',
+    /** Could not parse an Error frame body from the wire. */
+    clientDecodeFailure: 'yydb.client.decode_failure',
+    /** The YYDB session is already closed. */
+    sessionClosed: 'yydb.session.closed',
+};
+/**
+ * @deprecated Engine codes moved to Rust — use string literals or match on
+ * {@link YydbError.code} returned from {@link fromDiagnosticJson}. This table
+ * exists only for transition; new engine error variants will **not** be added here.
  */
-/** Stable codes known to the TypeScript hosts. */
 export const YydbErrorCodes = {
+    // Engine codes (deprecated)
     io: 'yydb.io',
     corrupt: 'yydb.corrupt',
     schemaConflict: 'yydb.schema.conflict',
@@ -25,30 +59,12 @@ export const YydbErrorCodes = {
     fencingMismatch: 'yydb.fencing.mismatch',
     leaseExpired: 'yydb.lease.expired',
     quotaExceeded: 'yydb.quota.exceeded',
-    sessionClosed: 'yydb.session.closed',
-    clientInvalidEndpoint: 'yydb.client.invalid_endpoint',
-    clientTransportFailure: 'yydb.client.transport_failure',
-    clientRequestIdMismatch: 'yydb.client.request_id_mismatch',
-    clientUnexpectedResponse: 'yydb.client.unexpected_response',
-    clientDecodeFailure: 'yydb.client.decode_failure',
+    // Client codes (still canonical for client-local errors)
+    ...YydbClientErrorCodes,
 };
-/**
- * Codes where retrying the same operation can legitimately succeed: a socket or
- * lease hiccup, or a compare-and-set that lost a benign race. Every other code
- * needs the caller to change input, schema, or wiring first.
- */
-const RETRYABLE_CODES = new Set([
-    YydbErrorCodes.clientTransportFailure,
-    YydbErrorCodes.casConflict,
-    YydbErrorCodes.leaseUnavailable,
-]);
-/** Whether `code` may be retried with the same arguments. */
-export function isRetryableYydbCode(code) {
-    return RETRYABLE_CODES.has(code);
-}
 /** YYDB failure with a stable machine-readable {@link YydbError.code}. */
 export class YydbError extends Error {
-    /** Stable code — engine code or `yydb.client.*`. */
+    /** Stable code — engine code (from Rust) or `yydb.client.*`. */
     code;
     /** Operation that failed. */
     operation;
@@ -61,8 +77,10 @@ export class YydbError extends Error {
         this.name = 'YydbError';
         this.code = code;
         this.operation = options.operation ?? 'unknown';
-        this.retryable = isRetryableYydbCode(code);
-        this.params = options.params;
+        this.retryable = options.retryable ?? false;
+        if (options.params !== undefined) {
+            this.params = options.params;
+        }
     }
     /**
      * Parse the diagnostic JSON that N-API and WASM surfaces embed in their
@@ -106,23 +124,28 @@ export class YydbError extends Error {
         else {
             return null;
         }
-        const code = typeof obj.code === 'string' ? obj.code : null;
-        const message = typeof obj.message === 'string' ? obj.message : '';
+        // WASM envelopes nest the diagnostic under `{ ok, error: {...} }`.
+        let diag = obj;
+        if (typeof obj['ok'] === 'boolean' && !obj['ok'] && obj['error'] && typeof obj['error'] === 'object') {
+            diag = obj['error'];
+        }
+        const code = typeof diag['code'] === 'string' ? diag['code'] : null;
+        const message = typeof diag['message'] === 'string' ? diag['message'] : '';
         if (!code)
             return null;
-        const operation = typeof obj.operation === 'string' ? obj.operation : undefined;
-        const retryable = typeof obj.retryable === 'boolean' ? obj.retryable : undefined;
-        const params = obj.params && typeof obj.params === 'object'
-            ? obj.params
+        const operation = typeof diag['operation'] === 'string' ? diag['operation'] : undefined;
+        const retryable = typeof diag['retryable'] === 'boolean' ? diag['retryable'] : undefined;
+        const params = diag['params'] && typeof diag['params'] === 'object'
+            ? diag['params']
             : undefined;
-        const err = new YydbError(code, message, {
-            operation,
-            params,
-        });
-        if (typeof retryable === 'boolean') {
-            err.retryable = retryable;
-        }
-        return err;
+        const opts = {};
+        if (operation !== undefined)
+            opts.operation = operation;
+        if (retryable !== undefined)
+            opts.retryable = retryable;
+        if (params !== undefined)
+            opts.params = params;
+        return new YydbError(code, message, opts);
     }
 }
 /** Narrowing helper so callers can branch without `instanceof` imports. */

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

@@ -0,0 +1,41 @@
+/** Parsed `{ ok, rows, error, code }` envelope from wasm VOS 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 parseWasmRowsResult(payload: string, operation: string): WasmRowsResult;
+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,56 @@
+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 parseWasmRowsResult(payload, operation) {
+    const parsed = parseJson(payload, operation);
+    if (!parsed.ok) {
+        throw envelopeError(parsed, operation);
+    }
+    return parsed;
+}
+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/udf-types.d.ts

@@ -0,0 +1,26 @@
+/** 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

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

package/dist/wasm/binding.d.ts

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

package/dist/wasm/database.d.ts

@@ -0,0 +1,54 @@
+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>;
+    /** 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 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;
+}