@yydb/yydb 0.0.11 → 0.0.15

package/dist/node/cli/init-cmd.js

@@ -0,0 +1,18 @@
+import { loadNative } from '../native.js';
+import { requiredPositional, str } from './options.js';
+export function registerInitCommand(cli) {
+    cli.command('init', 'cli.cmd.init')
+        .option('--schema-version <n>', 'cli.opt.schema-version')
+        .option('--schema-file <path>', 'cli.opt.schema-file')
+        .action((options) => cmdInit(options));
+}
+export function cmdInit(options) {
+    const dbPath = requiredPositional(options, 'init');
+    const schemaVersion = Number.parseInt(str(options, 'schema-version') ?? '1', 10);
+    const schemaFile = str(options, 'schema-file');
+    const native = loadNative();
+    const schemaDocument = schemaFile ? native.readSchemaFile(schemaFile) : null;
+    native.initDb(dbPath, schemaVersion, schemaDocument);
+    console.log(`initialized ${dbPath}`);
+    return 0;
+}

package/dist/node/cli/options.d.ts

@@ -0,0 +1,4 @@
+import type { ParsedOptions } from '@vmz/commander';
+export declare function str(options: ParsedOptions, key: string): string | undefined;
+export declare function flag(options: ParsedOptions, key: string): boolean;
+export declare function requiredPositional(options: ParsedOptions, label: string): string;

package/dist/node/cli/options.js

@@ -0,0 +1,14 @@
+export function str(options, key) {
+    const value = options[key];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+export function flag(options, key) {
+    return options[key] === true;
+}
+export function requiredPositional(options, label) {
+    const value = options._[0];
+    if (!value) {
+        throw new Error(`${label} requires a path argument`);
+    }
+    return value;
+}

package/dist/node/cli/serve-cmd.d.ts

@@ -0,0 +1,3 @@
+import type { Cli, ParsedOptions } from '@vmz/commander';
+export declare function registerServeCommand(cli: Cli): void;
+export declare function cmdServe(options: ParsedOptions): number;

package/dist/node/cli/serve-cmd.js

@@ -0,0 +1,14 @@
+import { loadNative } from '../native.js';
+import { flag, requiredPositional, str } from './options.js';
+export function registerServeCommand(cli) {
+    cli.command('serve', 'cli.cmd.serve')
+        .option('--bind <host:port>', 'cli.opt.bind')
+        .option('--insecure-bind', 'cli.opt.insecure-bind')
+        .action((options) => cmdServe(options));
+}
+export function cmdServe(options) {
+    const dbPath = requiredPositional(options, 'serve');
+    const bind = str(options, 'bind') ?? '127.0.0.1:7700';
+    loadNative().serve(dbPath, bind, flag(options, 'insecure-bind'));
+    return 0;
+}

package/dist/node/cli/version-cmd.d.ts

@@ -0,0 +1,3 @@
+import type { Cli } from '@vmz/commander';
+export declare function registerVersionCommand(cli: Cli): void;
+export declare function cmdVersion(): number;

package/dist/node/cli/version-cmd.js

@@ -0,0 +1,8 @@
+import { loadNative } from '../native.js';
+export function registerVersionCommand(cli) {
+    cli.command('version', 'cli.cmd.version').action(() => cmdVersion());
+}
+export function cmdVersion() {
+    console.log(loadNative().version());
+    return 0;
+}

package/dist/node/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/node/cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runCli } from './cli/cli.js';
+const code = await runCli(process.argv);
+if (code !== 0) {
+    process.exitCode = code;
+}

package/dist/node/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';
+export type { SchemaVersion } from '@yydb/yydb-client';
+export interface OpenOptions {
+    /** Override CLI script path (tests / special installs). */
+    cli?: string;
+    /** @deprecated Use `cli`. */
+    binary?: string;
+    /** Prefer a specific loopback port; default = ephemeral free port. */
+    port?: number;
+    /** Extra args after `serve <path> --bind …`. */
+    serveArgs?: string[];
+}
+/**
+ * Node-facing YYDB handle. Looks like one library; owns a private loopback
+ * `yydb serve` child under the hood.
+ */
+export declare class Database {
+    readonly path: string;
+    readonly endpoint: string;
+    private client;
+    private child;
+    private readonly microRegistry;
+    private constructor();
+    /**
+     * Open (create) a `.yydb` file. Spawns the engine on `127.0.0.1` automatically.
+     */
+    static open(dbPath: string, options?: OpenOptions): Promise<Database>;
+    serverVersion(): Promise<string>;
+    info(): Promise<string>;
+    getSchema(): Promise<import("@yydb/yydb-client").SchemaVersion | null>;
+    ensureSchema(version: number, document: string): Promise<void>;
+    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`](./database.ts) is called.
+     */
+    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 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. */
+    close(): Promise<void>;
+}

package/dist/node/database.js

@@ -0,0 +1,173 @@
+import { spawn } from 'node:child_process';
+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, udfWireKind, MicroSessionRegistry } from '../shared/micro.js';
+import { resolveYydbCli } from './resolve-bin.js';
+async function freeLoopbackPort() {
+    return await new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            if (!address || typeof address === 'string') {
+                server.close();
+                reject(new Error('could not allocate loopback port'));
+                return;
+            }
+            const { port } = address;
+            server.close((error) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve(port);
+            });
+        });
+        server.on('error', reject);
+    });
+}
+async function waitForTcp(host, port, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            await new Promise((resolve, reject) => {
+                const socket = net.connect({ host, port }, () => {
+                    socket.end();
+                    resolve();
+                });
+                socket.on('error', reject);
+            });
+            return;
+        }
+        catch {
+            await new Promise((r) => setTimeout(r, 40));
+        }
+    }
+    throw new Error(`yydb engine did not accept connections on ${host}:${port}`);
+}
+/**
+ * Node-facing YYDB handle. Looks like one library; owns a private loopback
+ * `yydb serve` child under the hood.
+ */
+export class Database {
+    path;
+    endpoint;
+    client;
+    child;
+    microRegistry;
+    constructor(dbPath, endpoint, client, child) {
+        this.path = dbPath;
+        this.endpoint = endpoint;
+        this.client = client;
+        this.child = child;
+        this.microRegistry = new MicroSessionRegistry();
+        this.client.setMicroHostHandler((payload) => this.microRegistry.invokeFromWire(payload));
+    }
+    /**
+     * Open (create) a `.yydb` file. Spawns the engine on `127.0.0.1` automatically.
+     */
+    static async open(dbPath, options = {}) {
+        const resolved = path.resolve(dbPath);
+        fs.mkdirSync(path.dirname(resolved), { recursive: true });
+        const cli = options.cli ?? options.binary ?? resolveYydbCli();
+        const port = options.port ?? (await freeLoopbackPort());
+        const bind = `127.0.0.1:${port}`;
+        const args = [cli, 'serve', resolved, '--bind', bind, ...(options.serveArgs ?? [])];
+        const child = spawn(process.execPath, args, {
+            stdio: 'pipe',
+            windowsHide: true,
+        });
+        let stderr = '';
+        child.stderr?.setEncoding('utf8');
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk;
+        });
+        const exitPromise = new Promise((_, reject) => {
+            child.once('exit', (code, signal) => {
+                reject(new Error(`yydb engine exited early (code=${code}, signal=${signal}): ${stderr.trim()}`));
+            });
+            child.once('error', reject);
+        });
+        try {
+            await Promise.race([waitForTcp('127.0.0.1', port, 8000), exitPromise]);
+            const client = await connect(bind);
+            child.removeAllListeners('exit');
+            child.removeAllListeners('error');
+            child.on('exit', () => {
+                /* closed via Database.close or crash */
+            });
+            return new Database(resolved, bind, client, child);
+        }
+        catch (error) {
+            child.kill('SIGTERM');
+            throw error;
+        }
+    }
+    async serverVersion() {
+        return this.client.serverVersion();
+    }
+    async info() {
+        return this.client.info();
+    }
+    async getSchema() {
+        return this.client.getSchema();
+    }
+    async ensureSchema(version, document) {
+        await this.client.ensureSchema(version, document);
+    }
+    async get(key) {
+        return this.client.get(key);
+    }
+    async put(key, value) {
+        await this.client.put(key, value);
+    }
+    /**
+     * Build a typed session-local micro definition. Does not register it with
+     * the engine until [`registerMicro`](./database.ts) is called.
+     */
+    defineMicro(definition) {
+        return buildMicro(definition);
+    }
+    /**
+     * 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`.
+     */
+    async registerMicro(definition) {
+        const handle = this.microRegistry.register(definition);
+        await this.client.registerMicro({
+            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),
+        });
+        return handle;
+    }
+    /** Invoke a registered scalar UDF on the private engine. */
+    async callScalar(name, version, args) {
+        return this.client.callScalar(name, version, args);
+    }
+    /** Stop the private engine process. */
+    async close() {
+        this.client.close();
+        const child = this.child;
+        this.child = null;
+        if (!child || child.exitCode !== null || child.killed) {
+            return;
+        }
+        await new Promise((resolve) => {
+            child.once('exit', () => resolve());
+            child.kill('SIGTERM');
+            setTimeout(() => {
+                if (child.exitCode === null && !child.killed) {
+                    child.kill('SIGKILL');
+                }
+                resolve();
+            }, 2000);
+        });
+    }
+}

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/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,33 +70,63 @@ 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. */
     cause?: unknown;
 }
 /** 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;
     /** Whether the same call may be retried. */
     readonly retryable: boolean;
+    /** Structured parameters for catalog templating (when present). */
+    readonly params?: Readonly<Record<string, string>>;
     constructor(code: YydbErrorCode, message: string, options?: YydbErrorOptions);
+    /**
+     * Parse the diagnostic JSON that N-API and WASM surfaces embed in their
+     * `Error.message`. Every boundary surface (N-API reason field, WASM JSON
+     * envelope, wire protocol) carries the same `{ code, operation, retryable,
+     * message, params? }` contract produced by `yydb::Error::to_json`.
+     *
+     * Returns the parsed {@link YydbError} if `value` is a diagnostic object,
+     * or `null` when the input is plain text. Hosts typically use this as a
+     * fallback in catch blocks:
+     *
+     * ```ts
+     * try {
+     *     await db.put('key', value);
+     * } catch (err) {
+     *     const parsed = YydbError.fromDiagnosticJson(
+     *         err instanceof Error ? err.message : String(err),
+     *     );
+     *     if (parsed) {
+     *         // branch on parsed.code / retryable / operation
+     *     }
+     * }
+     * ```
+     */
+    static fromDiagnosticJson(value: unknown): YydbError | null;
 }
 /** Narrowing helper so callers can branch without `instanceof` imports. */
 export declare function isYydbError(value: unknown): value is YydbError;