@yydb/yydb 0.0.11 → 0.0.15

package/README.md

@@ -1,86 +1,86 @@
-# `@yydb/yydb`
-
-Node embedded engine and CLI. `Database.open` starts a private loopback `yydb serve` process and talks over the YY
-wire protocol; platform `.node` bindings install through optional dependencies.
-
-Browsers are served by the pure TypeScript [`@yydb/light-db`](../light-db/readme.md) package. This package no longer
-ships a WebAssembly entry.
-
-For a wire client only (renderer or an app that already runs `yydb serve`), use
-[`@yydb/yydb-client`](https://www.npmjs.com/package/@yydb/yydb-client).
-
-[![npm](https://img.shields.io/npm/v/@yydb/yydb)](https://www.npmjs.com/package/@yydb/yydb)
-[![Node.js](https://img.shields.io/node/v/@yydb/yydb)](https://www.npmjs.com/package/@yydb/yydb)
-
-## Exports
-
-| Import | Runtime | Role |
-|--------|---------|------|
-| `@yydb/yydb` | Node | `Database.open`, micro helpers, VOS re-exports |
-| `@yydb/yydb/cli` | Node | CLI (`version`, `init`, `info`, `serve`) |
-
-Node.js 18+.
-
-Schema truth lives in the `.yydb` file via `ensureSchema` and VOS documents.
-
-## Example
-
-```ts
-import { Database } from '@yydb/yydb';
-
-const db = await Database.open('./data/app.yydb');
-
-await db.ensureSchema(
-    1,
-    `table Setting {
-        @@id: uuid,
-        key: utf8,
-        value: utf8,
-    }`,
-);
-
-await db.put('theme', 'dark');
-console.log(await db.get('theme'));
-await db.close();
-```
-
-The file is created when missing. Schema version and VOS document persist with the data.
-
-## API
-
-```ts
-const db = await Database.open(path, options?);
-
-await db.ensureSchema(version, vosDocument);
-await db.getSchema();
-await db.put(key, stringOrBytes);
-await db.get(key);
-await db.info();
-await db.serverVersion();
-await db.registerMicro(microDefinition);
-await db.callScalar('double', 1, [21]);
-await db.close();
-```
-
-`OpenOptions`: `cli` (explicit CLI script path), `port` (preferred loopback port), `serveArgs` (extra `yydb serve`
-arguments). `binary` is a deprecated alias for `cli`.
-
-The native binding exposes additive operations (`schemaVersion`, `schemaDocument`, `recordCount`, `journalMode`,
-`checkpoint`, `walFrameCount`, `get`, `put`); the CLI composes commands from them.
-
-## Related packages
-
-| Need | Package |
-|------|---------|
-| Node embedded engine and CLI (this package) | **`@yydb/yydb`** |
-| Browser, pure TypeScript | **`@yydb/light-db`** |
-| Wire client only | [`@yydb/yydb-client`](https://www.npmjs.com/package/@yydb/yydb-client) |
-| In-process Rust embed | [`yydb`](https://crates.io/crates/yydb) |
-| Agent skills (wire protocol) | [`@yydb/yydb-skills`](https://www.npmjs.com/package/@yydb/yydb-skills) |
-
-Electron: main process can use `@yydb/yydb`; renderer code can use `@yydb/yydb-client` against the main-process
-endpoint.
-
-The managed engine listens on `127.0.0.1` with no authentication — keep the endpoint private.
-
-[YYDB overview](https://github.com/yy-database/yydb.rs) · [User guides](https://github.com/yy-database/yydb.rs/tree/dev/projects/packages/homepage/documentation/zh-hans)
+# `@yydb/yydb`
+
+Node embedded engine and CLI. `Database.open` starts a private loopback `yydb serve` process and talks over the YY
+wire protocol; platform `.node` bindings install through optional dependencies.
+
+Browsers are served by the pure TypeScript [`@yydb/light-db`](../light-db/readme.md) package. This package no longer
+ships a WebAssembly entry.
+
+For a wire client only (renderer or an app that already runs `yydb serve`), use
+[`@yydb/yydb-client`](https://www.npmjs.com/package/@yydb/yydb-client).
+
+[![npm](https://img.shields.io/npm/v/@yydb/yydb)](https://www.npmjs.com/package/@yydb/yydb)
+[![Node.js](https://img.shields.io/node/v/@yydb/yydb)](https://www.npmjs.com/package/@yydb/yydb)
+
+## Exports
+
+| Import | Runtime | Role |
+|--------|---------|------|
+| `@yydb/yydb` | Node | `Database.open`, micro helpers, VOS re-exports |
+| `@yydb/yydb/cli` | Node | CLI (`version`, `init`, `info`, `serve`) |
+
+Node.js 18+.
+
+Schema truth lives in the `.yydb` file via `ensureSchema` and VOS documents.
+
+## Example
+
+```ts
+import { Database } from '@yydb/yydb';
+
+const db = await Database.open('./data/app.yydb');
+
+await db.ensureSchema(
+    1,
+    `table Setting {
+        @@id: uuid,
+        key: utf8,
+        value: utf8,
+    }`,
+);
+
+await db.put('theme', 'dark');
+console.log(await db.get('theme'));
+await db.close();
+```
+
+The file is created when missing. Schema version and VOS document persist with the data.
+
+## API
+
+```ts
+const db = await Database.open(path, options?);
+
+await db.ensureSchema(version, vosDocument);
+await db.getSchema();
+await db.put(key, stringOrBytes);
+await db.get(key);
+await db.info();
+await db.serverVersion();
+await db.registerMicro(microDefinition);
+await db.callScalar('double', 1, [21]);
+await db.close();
+```
+
+`OpenOptions`: `cli` (explicit CLI script path), `port` (preferred loopback port), `serveArgs` (extra `yydb serve`
+arguments). `binary` is a deprecated alias for `cli`.
+
+The native binding exposes additive operations (`schemaVersion`, `schemaDocument`, `recordCount`, `journalMode`,
+`checkpoint`, `walFrameCount`, `get`, `put`); the CLI composes commands from them.
+
+## Related packages
+
+| Need | Package |
+|------|---------|
+| Node embedded engine and CLI (this package) | **`@yydb/yydb`** |
+| Browser, pure TypeScript | **`@yydb/light-db`** |
+| Wire client only | [`@yydb/yydb-client`](https://www.npmjs.com/package/@yydb/yydb-client) |
+| In-process Rust embed | [`yydb`](https://crates.io/crates/yydb) |
+| Agent skills (wire protocol) | [`@yydb/yydb-skills`](https://www.npmjs.com/package/@yydb/yydb-skills) |
+
+Electron: main process can use `@yydb/yydb`; renderer code can use `@yydb/yydb-client` against the main-process
+endpoint.
+
+The managed engine listens on `127.0.0.1` with no authentication — keep the endpoint private.
+
+[YYDB overview](https://github.com/yy-database/yydb.rs) · [User guides](https://github.com/yy-database/yydb.rs/tree/dev/projects/packages/homepage/documentation/zh-hans)

package/dist/api/database.d.ts

@@ -1,5 +1,6 @@
 import { type EmittableItem } from '@voml/vos';
 import { defineMicro as buildMicro, type DefinedMicro, type MicroHandle } from '../shared/micro.js';
+import { loadNative } from '../native/binding.js';
 import type { UdfScalarDescriptor } from '../shared/udf-types.js';
 /** Published schema metadata. */
 export interface SchemaVersion {
@@ -11,6 +12,86 @@ export interface OpenOptions {
     /** Create parent directories when missing (default: true). */
     mkdir?: boolean;
 }
+/** One row from a {@link Database.scan}. */
+export interface ScanRow {
+    key: string;
+    value: Uint8Array;
+}
+/** Options for {@link Database.scan}. */
+export interface ScanOptions {
+    /** Include this prefix in every returned key; default `""` returns everything. */
+    prefix?: string;
+    /** Exclusive continuation cursor from a previous scan's last row; default `null` starts fresh. */
+    after?: string | null;
+    /** Max rows returned per call; default `1000`. */
+    limit?: number;
+}
+/** One change in a {@link Database.batch}. Use `null` to delete. */
+export interface BatchChange {
+    key: string;
+    value: Uint8Array | string | null;
+}
+/** Options for {@link Database.migrateSchema}. */
+export interface MigrateOptions {
+    /** Rename entries — `fromType`/`toType` updates a type name; `type`/`fromField`/`toField` updates one field. */
+    renames?: ReadonlyArray<{
+        fromType: string;
+        toType: string;
+    } | {
+        type: string;
+        fromField: string;
+        toField: string;
+    }>;
+}
+/** One consistency finding from {@link Database.doctor}. */
+export interface DoctorIssue {
+    severity: 'warn' | 'error';
+    code: string;
+    message: string;
+    key_hint?: string | null;
+}
+/** Per-namespace usage snapshot from {@link Database.doctor}. */
+export interface DoctorNamespaceStats {
+    prefix: string;
+    record_count: number;
+    bytes_used: number;
+    object_bytes: number;
+    quota_max_bytes?: number | null;
+    ttl_expired_pending: number;
+}
+/** Read-only consistency report. */
+export interface DoctorReport {
+    file_path?: string | null;
+    last_commit_sequence: number;
+    last_checkpoint_sequence: number;
+    checkpoint_lag_records: number;
+    wal_bytes_uncheckpointed: number;
+    orphan_object_count: number;
+    namespaces: DoctorNamespaceStats[];
+    issues: DoctorIssue[];
+}
+/** Summary of a v0 `.yydx` compaction pass. */
+export interface CompactReport {
+    checkpointed: boolean;
+    orphans_reclaimed: number;
+}
+/**
+ * Transaction-local handle passed to {@link Database.transaction} callbacks.
+ * All CRUD methods forward to the underlying native handle while the
+ * transaction is in flight. Commit/rollback are owned by {@link Database}.
+ */
+export declare class TransactionHandle {
+    private readonly native;
+    constructor(native: ReturnType<ReturnType<typeof loadNative>['Database']['open']>);
+    get(key: string): Promise<Uint8Array | null>;
+    put(key: string, value: Uint8Array | string): Promise<void>;
+    delete(key: string): Promise<void>;
+    scan(options?: ScanOptions): Promise<ScanRow[]>;
+    batch(changes: readonly BatchChange[]): Promise<void>;
+    compareExchange(key: string, expected: Uint8Array | string | null, replacement: Uint8Array | string | null): Promise<boolean>;
+    query<T = Record<string, unknown>>(source: string): Promise<T[]>;
+    execute(source: string): Promise<void>;
+}
 /**
  * Node-facing YYDB local database handle.
  *
@@ -39,26 +120,60 @@ export declare class Database {
      * Accepts either a raw `.vos` source string, one `@voml/vos` descriptor
      * (`v.table()`, `v.class()`) or a list of descriptors. When descriptors
      * are supplied, they are rendered to source via `emitSource` first.
-     *
-     * ```ts
-     * // Raw source (unchanged behaviour):
-     * await db.ensureSchema('namespace demo { table User { @@id: uuid } }');
-     *
-     * // Zod-like builder — the Vos schema-ecosystem sweet spot:
-     * const User = v.table('User', { id: v.uuid().primary(), name: v.utf8() });
-     * await db.ensureSchema(User);
-     *
-     * // Multiple declarations in one shot:
-     * await db.ensureSchema(TableA, TableB, ClassC);
-     * ```
      */
     ensureSchema(...input: [string] | [string, ...EmittableItem[]] | EmittableItem[]): Promise<void>;
     /** Read one record, or `null` when the key is absent. */
     get(key: string): Promise<Uint8Array | null>;
     /** Insert or replace one record. */
     put(key: string, value: Uint8Array | string): Promise<void>;
+    /** Delete one record by key. Silently succeeds when the key is absent. */
+    delete(key: string): Promise<void>;
+    /** List key/value pairs in lexical order. `prefix` defaults to `""` (all keys). */
+    scan(options?: ScanOptions): Promise<ScanRow[]>;
+    /** Atomically write or delete many keys in one call. */
+    batch(changes: readonly BatchChange[]): Promise<void>;
+    /**
+     * Compare-and-swap: replace or delete `key` only when its current value
+     * exactly equals `expected`. Both `expected` and `replacement` may be
+     * `null` (meaning absent / delete). Returns `true` when the swap applied.
+     */
+    compareExchange(key: string, expected: Uint8Array | string | null, replacement: Uint8Array | string | null): Promise<boolean>;
     /** Fold the WAL into the main file and truncate the sidecar. */
     checkpoint(): Promise<void>;
+    /** Checkpoint then copy a self-contained `.yydb` main file to `dest`. */
+    backup(dest: string): Promise<void>;
+    /** Copy main + WAL + SHM without checkpoint; opening `dest` replays the WAL tail. */
+    backupWithWal(dest: string): Promise<void>;
+    /** Run read-only consistency probes against the database. */
+    doctor(): Promise<DoctorReport>;
+    /** Fold WAL + reclaim orphan blobs (`.yydx` layouts only). */
+    compactYydx(): Promise<CompactReport>;
+    /**
+     * Run `fn` inside an explicit transaction. The transaction commits on
+     * normal return and rolls back on throw. Nested calls are not supported.
+     *
+     * ```ts
+     * await db.transaction(async (tx) => {
+     *     await tx.put('a', '1');
+     *     await tx.put('b', '2');
+     * });
+     * ```
+     */
+    transaction<T>(fn: (tx: TransactionHandle) => Promise<T>): Promise<T>;
+    /** Execute a VOS read pipeline and return typed rows. */
+    query<T = Record<string, unknown>>(source: string): Promise<T[]>;
+    /** Execute a VOS write program. */
+    execute(source: string): Promise<void>;
+    /**
+     * Publish a new schema version, migrating existing records when their
+     * shape no longer matches.
+     *
+     * Accepts raw `.vos` source or `@voml/vos` descriptors (same as
+     * {@link Database.ensureSchema}). Use `renames` to tell the engine which
+     * old type/field names map to the new ones — records that would otherwise
+     * look structurally unrelated get preserved.
+     */
+    migrateSchema(documentOrSource: string | EmittableItem, ...rest: (EmittableItem | MigrateOptions)[]): Promise<void>;
     /** Build a typed session-local micro definition (without registering). */
     defineMicro<TArgs extends readonly UdfScalarDescriptor[], TReturn extends UdfScalarDescriptor>(definition: Parameters<typeof buildMicro<TArgs, TReturn>>[0]): DefinedMicro<TArgs, TReturn>;
     /**

package/dist/api/database.js

@@ -3,6 +3,44 @@ import path from 'node:path';
 import { emitSource, } from '@voml/vos';
 import { defineMicro as buildMicro, microFingerprint, udfWireKind, MicroSessionRegistry, } from '../shared/micro.js';
 import { loadNative } from '../native/binding.js';
+import { YydbError } from '../shared/errors.js';
+/**
+ * Transaction-local handle passed to {@link Database.transaction} callbacks.
+ * All CRUD methods forward to the underlying native handle while the
+ * transaction is in flight. Commit/rollback are owned by {@link Database}.
+ */
+export class TransactionHandle {
+    native;
+    constructor(native) {
+        this.native = native;
+    }
+    async get(key) { return this.native.get(key); }
+    async put(key, value) {
+        const bytes = typeof value === 'string' ? new TextEncoder().encode(value) : value;
+        this.native.put(key, bytes);
+    }
+    async delete(key) { this.native.delete(key); }
+    async scan(options = {}) {
+        const rowsJson = this.native.scanPrefix(options.prefix ?? '', options.after ?? null, options.limit ?? 1000);
+        const rows = JSON.parse(rowsJson);
+        return rows.map((r) => ({ key: r.key, value: new Uint8Array(r.value) }));
+    }
+    async batch(changes) {
+        const body = changes.map((c) => ({
+            key: c.key,
+            value: c.value === null ? null : typeof c.value === 'string' ? Array.from(new TextEncoder().encode(c.value)) : Array.from(c.value),
+        }));
+        this.native.writeBatch(JSON.stringify(body));
+    }
+    async compareExchange(key, expected, replacement) {
+        const toBytes = (v) => v === null ? null : typeof v === 'string' ? new TextEncoder().encode(v) : v;
+        return this.native.compareExchange(key, toBytes(expected), toBytes(replacement));
+    }
+    async query(source) {
+        return JSON.parse(this.native.queryVos(source));
+    }
+    async execute(source) { this.native.executeVosWrite(source); }
+}
 /**
  * Node-facing YYDB local database handle.
  *
@@ -57,27 +95,13 @@ export class Database {
      * Accepts either a raw `.vos` source string, one `@voml/vos` descriptor
      * (`v.table()`, `v.class()`) or a list of descriptors. When descriptors
      * are supplied, they are rendered to source via `emitSource` first.
-     *
-     * ```ts
-     * // Raw source (unchanged behaviour):
-     * await db.ensureSchema('namespace demo { table User { @@id: uuid } }');
-     *
-     * // Zod-like builder — the Vos schema-ecosystem sweet spot:
-     * const User = v.table('User', { id: v.uuid().primary(), name: v.utf8() });
-     * await db.ensureSchema(User);
-     *
-     * // Multiple declarations in one shot:
-     * await db.ensureSchema(TableA, TableB, ClassC);
-     * ```
      */
     async ensureSchema(...input) {
         let document;
         if (typeof input[0] === 'string') {
-            // Raw source string, optionally followed by descriptors we just ignore.
             document = input[0];
         }
         else {
-            // One or more Vos descriptor items → render to source.
             document = emitSource(input);
         }
         this.native.ensureSchema(document);
@@ -91,10 +115,128 @@ export class Database {
         const bytes = typeof value === 'string' ? new TextEncoder().encode(value) : value;
         this.native.put(key, bytes);
     }
+    /** Delete one record by key. Silently succeeds when the key is absent. */
+    async delete(key) {
+        this.native.delete(key);
+    }
+    /** List key/value pairs in lexical order. `prefix` defaults to `""` (all keys). */
+    async scan(options = {}) {
+        const rowsJson = this.native.scanPrefix(options.prefix ?? '', options.after ?? null, options.limit ?? 1000);
+        const rows = JSON.parse(rowsJson);
+        return rows.map((r) => ({ key: r.key, value: new Uint8Array(r.value) }));
+    }
+    /** Atomically write or delete many keys in one call. */
+    async batch(changes) {
+        const body = changes.map((c) => ({
+            key: c.key,
+            value: c.value === null
+                ? null
+                : typeof c.value === 'string'
+                    ? Array.from(new TextEncoder().encode(c.value))
+                    : Array.from(c.value),
+        }));
+        this.native.writeBatch(JSON.stringify(body));
+    }
+    /**
+     * Compare-and-swap: replace or delete `key` only when its current value
+     * exactly equals `expected`. Both `expected` and `replacement` may be
+     * `null` (meaning absent / delete). Returns `true` when the swap applied.
+     */
+    async compareExchange(key, expected, replacement) {
+        const toBytes = (v) => v === null ? null : typeof v === 'string' ? new TextEncoder().encode(v) : v;
+        return this.native.compareExchange(key, toBytes(expected), toBytes(replacement));
+    }
     /** Fold the WAL into the main file and truncate the sidecar. */
     async checkpoint() {
         this.native.checkpoint();
     }
+    /** Checkpoint then copy a self-contained `.yydb` main file to `dest`. */
+    async backup(dest) {
+        this.native.backup(dest);
+    }
+    /** Copy main + WAL + SHM without checkpoint; opening `dest` replays the WAL tail. */
+    async backupWithWal(dest) {
+        this.native.backupWithWal(dest);
+    }
+    /** Run read-only consistency probes against the database. */
+    async doctor() {
+        return JSON.parse(this.native.doctor());
+    }
+    /** Fold WAL + reclaim orphan blobs (`.yydx` layouts only). */
+    async compactYydx() {
+        return JSON.parse(this.native.compactYydx());
+    }
+    /**
+     * Run `fn` inside an explicit transaction. The transaction commits on
+     * normal return and rolls back on throw. Nested calls are not supported.
+     *
+     * ```ts
+     * await db.transaction(async (tx) => {
+     *     await tx.put('a', '1');
+     *     await tx.put('b', '2');
+     * });
+     * ```
+     */
+    async transaction(fn) {
+        this.native.begin();
+        const tx = new TransactionHandle(this.native);
+        try {
+            const result = await fn(tx);
+            this.native.commit();
+            return result;
+        }
+        catch (err) {
+            try {
+                this.native.rollback();
+            }
+            catch {
+                // rollback already failed, don't mask the original error
+            }
+            throw YydbError.fromDiagnosticJson(err instanceof Error ? err.message : String(err)) ?? err;
+        }
+    }
+    /** Execute a VOS read pipeline and return typed rows. */
+    async query(source) {
+        const rowsJson = this.native.queryVos(source);
+        return JSON.parse(rowsJson);
+    }
+    /** Execute a VOS write program. */
+    async execute(source) {
+        this.native.executeVosWrite(source);
+    }
+    /**
+     * Publish a new schema version, migrating existing records when their
+     * shape no longer matches.
+     *
+     * Accepts raw `.vos` source or `@voml/vos` descriptors (same as
+     * {@link Database.ensureSchema}). Use `renames` to tell the engine which
+     * old type/field names map to the new ones — records that would otherwise
+     * look structurally unrelated get preserved.
+     */
+    async migrateSchema(documentOrSource, ...rest) {
+        let document;
+        let options = {};
+        const all = [documentOrSource, ...rest];
+        const last = all[all.length - 1];
+        if (last &&
+            typeof last === 'object' &&
+            !('table' in last) &&
+            !('class' in last) &&
+            !('emit' in last) &&
+            ('renames' in last || Object.keys(last).length === 0)) {
+            options = all.pop() ?? {};
+        }
+        if (typeof all[0] === 'string') {
+            document = all[0];
+        }
+        else {
+            document = emitSource(all);
+        }
+        const renamesJson = options.renames?.length
+            ? JSON.stringify(options.renames)
+            : null;
+        this.native.migrateSchema(document, renamesJson);
+    }
     /** Build a typed session-local micro definition (without registering). */
     defineMicro(definition) {
         return buildMicro(definition);

package/dist/cli/cli.js

@@ -1,16 +1,22 @@
-import { dirname, join } from 'node:path';
+import fs from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createCli } from '@vmz/commander';
+import { formatDiagnostic } from '@vmz/diagnostic';
+import { YydbError } from '../shared/errors.js';
 import { registerInfoCommand } from './info-cmd.js';
 import { registerInitCommand } from './init-cmd.js';
 import { registerServeCommand } from './serve-cmd.js';
+import { registerVerifyCommand } from './verify-cmd.js';
 import { registerVersionCommand } from './version-cmd.js';
+const CLI_CATALOG = JSON.parse(fs.readFileSync(resolve(import.meta.dirname, '../../locales/en-US/cli.json'), 'utf8'));
 function buildYydbCli() {
     const localesRoot = join(dirname(fileURLToPath(import.meta.url)), '../../locales');
     const cli = createCli('yydb').locales(localesRoot).intro('cli.intro');
     registerVersionCommand(cli);
     registerInitCommand(cli);
     registerInfoCommand(cli);
+    registerVerifyCommand(cli);
     registerServeCommand(cli);
     return cli;
 }
@@ -19,6 +25,27 @@ export async function runCli(argv) {
         return await buildYydbCli().parse(argv);
     }
     catch (error) {
+        const parsed = error instanceof Error
+            ? YydbError.fromDiagnosticJson(error.message)
+            : null;
+        if (parsed) {
+            // Structured engine error from N-API / wire / WASM envelope.
+            const severity = parsed.retryable ? 'warning' : 'error';
+            const text = formatDiagnostic({
+                path: '',
+                severity,
+                code: parsed.code,
+                args: parsed.params,
+                message: error instanceof Error ? error.message : String(error),
+            }, {
+                locale: 'en-US',
+                catalog: CLI_CATALOG,
+                style: 'compact',
+            });
+            console.error(text);
+            return parsed.retryable ? 13 : 1;
+        }
+        // Plain text fallback (commander parse failures, unknown errors).
         console.error(`error: ${error instanceof Error ? error.message : String(error)}`);
         return 1;
     }

package/dist/cli/info-cmd.js

@@ -1,10 +1,17 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { formatDiagnostic } from '@vmz/diagnostic';
 import { loadNative } from '../native/binding.js';
 import { requiredPositional } from './options.js';
+const CLI_CATALOG = JSON.parse(fs.readFileSync(path.resolve(import.meta.dirname, '../../locales/en-US/cli.json'), 'utf8'));
 export function registerInfoCommand(cli) {
-    cli.command('info', 'cli.cmd.info').action((options) => cmdInfo(options));
+    cli.command('info', 'cli.cmd.info')
+        .option('--doctor', 'cli.opt.doctor')
+        .action((options) => cmdInfo(options));
 }
 export function cmdInfo(options) {
     const dbPath = requiredPositional(options, 'info');
+    const wantDoctor = Boolean(options.doctor);
     const database = loadNative().Database.open(dbPath);
     const lines = [`path=${database.path() ?? '<memory>'}`];
     const schemaVersion = database.schemaVersion();
@@ -25,6 +32,28 @@ export function cmdInfo(options) {
         lines.push(`shm=${shm}`);
     lines.push(`wal_frames=${database.walFrameCount()}`);
     console.log(lines.join('\n'));
+    if (wantDoctor) {
+        const report = JSON.parse(database.doctor());
+        if (report.issues.length === 0) {
+            console.log(`doctor=clean orphan_objects=${report.orphan_object_count}`);
+        }
+        else {
+            for (const issue of report.issues) {
+                const severity = issue.severity === 'error' ? 'error' : 'warning';
+                console.error(formatDiagnostic({
+                    path: dbPath,
+                    severity,
+                    code: issue.code,
+                    message: issue.message,
+                }, {
+                    locale: 'en-US',
+                    catalog: CLI_CATALOG,
+                    style: 'compact',
+                }));
+            }
+            console.error(`doctor=issues(${report.issues.length}) orphans=${report.orphan_object_count}`);
+        }
+    }
     return 0;
 }
 function summarizeDocument(document) {

package/dist/cli/verify-cmd.d.ts

@@ -0,0 +1,11 @@
+import type { Cli, ParsedOptions } from '@vmz/commander';
+export declare function registerVerifyCommand(cli: Cli): void;
+/**
+ * Run read-only consistency probes against a YYDB database file.
+ *
+ * Exit codes:
+ *   0  — clean (no issues)
+ *   1  — doctor found at least one error (database may be corrupt)
+ *   13 — only warnings present (readable but should be inspected)
+ */
+export declare function cmdVerify(options: ParsedOptions): number;