@zhin.js/gateway 1.1.2 → 1.2.0

package/README.md

@@ -3,7 +3,7 @@
 Zhin.js 管理网关（[ADR 0054](../../../docs/adr/0054-management-gateway.md)）。网关负责宿主层面的事：Console 账号与权限、终端、
 项目配置与 `.env`、依赖事务、实例监管。它**不依赖 `zhin.js` 与 IM 层**，不加载插件代码（`pnpm check:architecture` 强制）。
 
-网关进程（`zhin start`；前台运行用 `zhin start --foreground`）自己打开项目数据库并持有 `console_*` 表：登录、初始化、`iam.*`、`onboarding.update`、终端与审计
+网关进程（`zhin start`；前台运行用 `zhin start --foreground`）把 `console_*` 账号表放在自己的 `.zhin/gateway.db`（ADR 0059，与项目数据库方言无关；升级时自动从项目数据库迁入）：登录、初始化、`iam.*`、`onboarding.update`、终端与审计
 都在网关里，没有实例时 Console 照样可用；受管实例只按转发的主体做授权。`--standalone`（开发 / 测试，无网关）的实例仍在进程内
 装配 `installConsoleIam` / `installHostConsoleTerminal`。
 
@@ -27,7 +27,7 @@ zhin console init           # 首次创建 Console 所有者；之后 http.token
 
 | 子路径 | 内容 |
 |---|---|
-| `@zhin.js/gateway/iam` | Console 账号、角色、会话、API 令牌、审计与初始化（ADR 0049）：`ConsoleIamService`、`ConsoleSetupService`、`installConsoleIam`、`registerConsoleAuthRoutes`、`dispatchIamRpc` |
+| `@zhin.js/gateway/iam` | Console 账号、角色、会话、API 令牌、审计与初始化（ADR 0049）：`ConsoleIamService`、`ConsoleSetupService`、`installConsoleIam`、`registerConsoleAuthRoutes`、`dispatchIamRpc`、`importLegacyIamTables` / `revertLegacyIamImport` / `inspectLegacyIamImport`（旧版项目库账号表迁入 gateway.db 与回退，ADR 0059） |
 | `@zhin.js/gateway/terminal` | Console 终端（ADR 0051）：`TerminalService`、`installHostConsoleTerminal`、`parseTerminalConfig` |
 | `@zhin.js/gateway/config` | 原始配置文件与 `.env` 读写：`ConsoleConfigurationStore`、`readEnvFile` / `writeEnvFile`、配置路径与补丁、Console Schema |
 | `@zhin.js/gateway/plugin-management` | 项目级依赖事务：`PluginManagementWorkflow`、`PluginManagementActivity`、插件用例 |
@@ -36,8 +36,8 @@ zhin console init           # 首次创建 Console 所有者；之后 http.token
 | `@zhin.js/gateway/usage` | 用量统计聚合 |
 | `@zhin.js/gateway/onboarding` | Console 引导（ADR 0053）：`.zhin/onboarding.json` 状态（`OnboardingStateStore`、自动识别已配置步骤）、`OnboardingService`、安装白名单与 `authorizeInstall`、流式 `installPackages` |
 | `@zhin.js/gateway/http` | HTML / SSE 响应工具（实例也导入，不加载 Node HTTP 栈） |
-| `@zhin.js/gateway/server` | 网关 HTTP 服务器（`GatewayHttpServer`：自有路由、`{base}` 认证后转发、其他路由原样转发、实例离线 503 / 超时 504 / 其他 502；`useConsoleRpc` 登记更多网关 RPC）、`gateway.*` Console RPC 路由、`startGatewayConsole`（项目数据库、本地认证、`/auth/*`、`iam.*`、`onboarding.update`、初始化向导、终端、审计）、`registerGatewayEventRoutes`（合并 `{base}/events`、`{base}/gateway/packages/progress`）、`startGateway`（服务器 + Console + 实例监管 + `@zhin.js/host-http/bridge` 实例传输）、`runGateway`（`zhin start` 的监管 + 网关入口） |
-| `@zhin.js/gateway/database` | 网关自己的项目数据库连接（ADR 0054 §7）：`loadProjectDatabaseConfig` / `resolveProjectDatabaseConfig`（与实例 `resolveDatabaseConfig` 同一规则）、`ProjectDatabase`（SQLite WAL；不用同步的 `busy_timeout`，`SQLITE_BUSY` 以异步退避重试，默认 5 秒预算，超时返回 `503 database_busy` 与 `Retry-After`） |
+| `@zhin.js/gateway/server` | 网关 HTTP 服务器（`GatewayHttpServer`：自有路由、`{base}` 认证后转发、其他路由原样转发、实例离线 503 / 超时 504 / 其他 502；`useConsoleRpc` 登记更多网关 RPC）、`gateway.*` Console RPC 路由、`startGatewayConsole`（gateway.db、旧表迁移、本地认证、`/auth/*`、`iam.*`、`onboarding.update`、初始化向导、终端、审计）、`registerGatewayEventRoutes`（合并 `{base}/events`、`{base}/gateway/packages/progress`）、`startGateway`（服务器 + Console + 实例监管 + `@zhin.js/host-http/bridge` 实例传输）、`runGateway`（`zhin start` 的监管 + 网关入口） |
+| `@zhin.js/gateway/database` | 网关自己的存储与临时项目库连接（ADR 0054 §7、ADR 0059）：`openGatewayStore`（`.zhin/gateway.db`，`0600`，`gateway_meta`）、`loadProjectDatabaseConfig` / `resolveProjectDatabaseConfig`（与实例 `resolveDatabaseConfig` 同一规则，含 `database.console`）、`ProjectDatabase`（SQLite WAL；不用同步的 `busy_timeout`，`SQLITE_BUSY` 以异步退避重试，默认 5 秒预算，超时返回 `503 database_busy` 与 `Retry-After`；`tableExists` / `readSnapshot` / `dropTables` 供迁移使用）、`setupConsoleRole`（`zhin db console-role`：PostgreSQL / MySQL 的 Console SQL 受限账号） |
 | `@zhin.js/gateway` | 以上全部 |
 
 ```ts

package/lib/database/config.js

@@ -53,6 +53,32 @@ function normalizeRedisDatabase(value) {
     }
     return normalized;
 }
+/** `database.console` (ADR 0059 §4; port of the instance's check): PostgreSQL / MySQL only. */
+function normalizeConsoleCredential(config) {
+    if (!('console' in config) || config.console === undefined)
+        return;
+    const value = config.console;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw configurationError('database.console', '必须是对象 { user, password }');
+    const block = { ...value };
+    // `${ZHIN_DB_CONSOLE_*}` not set (yet): no restricted account — raw SQL stays off, the rest works.
+    if ((block.user === undefined || block.user === '') && (block.password === undefined || block.password === '')) {
+        delete config.console;
+        return;
+    }
+    normalizeRequiredText(block, 'user', 'database.console.user', 'ZHIN_DB_CONSOLE_USER=zhin_console_xxxxxxxx');
+    if (typeof block.password !== 'string' || block.password === '') {
+        throw configurationError('database.console.password', '不能为空', 'ZHIN_DB_CONSOLE_PASSWORD=…（zhin db console-role 生成）');
+    }
+    if (String(block.user) === String(config.user ?? '')) {
+        throw configurationError('database.console.user', '不能与主账号 database.user 相同（原始 SQL 只在受限账号上执行）');
+    }
+    for (const key of Object.keys(block)) {
+        if (key !== 'user' && key !== 'password')
+            throw configurationError(`database.console.${key}`, '不支持（只有 user 与 password）');
+    }
+    config.console = Object.freeze({ user: block.user, password: block.password });
+}
 /** Validates an expanded `database` block (port of `normalizeDatabaseHostConfig`). */
 export function normalizeProjectDatabaseConfig(input) {
     const dialect = input.dialect;
@@ -60,6 +86,9 @@ export function normalizeProjectDatabaseConfig(input) {
         throw new TypeError(`数据库配置 database.dialect 不支持 ${JSON.stringify(dialect)}；可选值为 sqlite、mysql、pg、mongodb、redis、memory。`);
     }
     const config = { ...input, dialect };
+    if (dialect !== 'pg' && dialect !== 'mysql')
+        delete config.console;
+    delete config.denyAttach;
     switch (dialect) {
         case 'mysql':
             normalizeOptionalText(config, 'host', 'database.host', 'DB_HOST=127.0.0.1');
@@ -69,6 +98,7 @@ export function normalizeProjectDatabaseConfig(input) {
             config.port = normalizePort(config.port, 'database.port', 'DB_PORT=3306');
             if (config.port === undefined)
                 delete config.port;
+            normalizeConsoleCredential(config);
             break;
         case 'pg':
             normalizeOptionalText(config, 'host', 'database.host', 'DB_HOST=127.0.0.1');
@@ -78,6 +108,7 @@ export function normalizeProjectDatabaseConfig(input) {
             config.port = normalizePort(config.port, 'database.port', 'DB_PORT=5432');
             if (config.port === undefined)
                 delete config.port;
+            normalizeConsoleCredential(config);
             break;
         case 'mongodb':
             normalizeRequiredText(config, 'url', 'database.url', 'DB_URL=mongodb://127.0.0.1:27017');

package/lib/database/console-role.d.ts

@@ -0,0 +1,35 @@
+import { type ConsoleCredentialDialect } from '@zhin.js/database';
+export declare const CONSOLE_ROLE_USER_ENV = "ZHIN_DB_CONSOLE_USER";
+export declare const CONSOLE_ROLE_PASSWORD_ENV = "ZHIN_DB_CONSOLE_PASSWORD";
+/** Stands for the password in `--print-sql` output (the real one is only written to `.env`). */
+export declare const CONSOLE_ROLE_PASSWORD_PLACEHOLDER = "<ZHIN_DB_CONSOLE_PASSWORD>";
+export declare class ConsoleRoleError extends Error {
+    readonly code: 'unsupported' | 'unavailable' | 'pending_migration' | 'denied';
+    constructor(code: 'unsupported' | 'unavailable' | 'pending_migration' | 'denied', message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface SetupConsoleRoleOptions {
+    readonly projectRoot: string;
+    /** Selects `.env.<environment>` for `${…}` (default `development`). */
+    readonly environment?: string;
+    /** Role name (default `zhin_console_<hash of the project root>`). */
+    readonly role?: string;
+    /**
+     * Do not create the account: write the password to `.env` and the reference to the config,
+     * and return the statements for a DBA (password shown as {@link CONSOLE_ROLE_PASSWORD_PLACEHOLDER}).
+     */
+    readonly printSql?: boolean;
+}
+export interface SetupConsoleRoleResult {
+    readonly dialect: ConsoleCredentialDialect;
+    readonly user: string;
+    /** Created / rotated by this run (false with `printSql`). */
+    readonly provisioned: boolean;
+    /** The statements (password replaced by the placeholder). */
+    readonly statements: readonly string[];
+    readonly envFile: string;
+}
+export declare function setupConsoleRole(options: SetupConsoleRoleOptions): Promise<SetupConsoleRoleResult>;
+/** The default role name of a project (what `zhin db console-role` creates). */
+export declare function defaultConsoleRoleName(projectRoot: string): string;

package/lib/database/console-role.js

@@ -0,0 +1,108 @@
+/**
+ * `zhin db console-role` and `zhin doctor --fix` (ADR 0059 §4): create the restricted database
+ * account raw Console SQL runs on (PostgreSQL / MySQL), with the main account, store its password
+ * in `.env` and reference it from `database.console`. Never run at instance start: the instance
+ * only probes the account (and refreshes PostgreSQL grants).
+ */
+import { join } from 'node:path';
+import { createConfigDocument } from '@zhin.js/runtime';
+import { DEFAULT_ROOT_CONFIG_FILE_NAME } from '@zhin.js/plugin-runtime';
+import { consoleRoleName, generateConsolePassword, planConsoleRole, provisionConsoleRole, scrubSecret, } from '@zhin.js/database';
+import { ConsoleConfigurationStore } from '../config/configuration.js';
+import { readEnvFile, writeEnvFile } from '../config/environment-files.js';
+import { upsertDotenv } from '../iam/setup-service.js';
+import { IAM_TABLES } from '../iam/tables.js';
+import { findConfigFile } from '../project/config-file.js';
+import { loadExpandedProjectConfig, resolveProjectDatabaseConfig } from './config.js';
+import { ProjectDatabase } from './project-database.js';
+export const CONSOLE_ROLE_USER_ENV = 'ZHIN_DB_CONSOLE_USER';
+export const CONSOLE_ROLE_PASSWORD_ENV = 'ZHIN_DB_CONSOLE_PASSWORD';
+/** Stands for the password in `--print-sql` output (the real one is only written to `.env`). */
+export const CONSOLE_ROLE_PASSWORD_PLACEHOLDER = `<${CONSOLE_ROLE_PASSWORD_ENV}>`;
+export class ConsoleRoleError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'ConsoleRoleError';
+    }
+}
+const ENV_REFERENCE = { user: `\${${CONSOLE_ROLE_USER_ENV}}`, password: `\${${CONSOLE_ROLE_PASSWORD_ENV}}` };
+export async function setupConsoleRole(options) {
+    const { projectRoot } = options;
+    const expanded = await loadExpandedProjectConfig(projectRoot, options.environment ?? 'development');
+    const config = await resolveProjectDatabaseConfig(projectRoot, expanded);
+    if (config.dialect !== 'pg' && config.dialect !== 'mysql') {
+        throw new ConsoleRoleError('unsupported', `项目数据库是 ${config.dialect}：只有 PostgreSQL / MySQL 需要受限账号（SQLite 的 Console 账号在另一个文件里，且实例连接拒绝 ATTACH）`);
+    }
+    const dialect = config.dialect;
+    const main = new ProjectDatabase(config);
+    try {
+        await main.start();
+    }
+    catch (error) {
+        throw new ConsoleRoleError('unavailable', `无法用主账号连接项目数据库：${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    const password = generateConsolePassword();
+    let statements;
+    let user;
+    try {
+        // The old console_* tables would be inside a MySQL database-wide grant: import them first.
+        const legacy = await main.tableExists(Object.values(IAM_TABLES));
+        if (legacy.length) {
+            throw new ConsoleRoleError('pending_migration', `项目数据库里还有旧版的 Console 账号表（${legacy.join(', ')}）：先运行 zhin start 或 zhin console migrate 完成迁移`);
+        }
+        const run = (sql, params) => main.query(sql, params);
+        const request = { dialect, projectKey: projectRoot, password, ...(options.role ? { role: options.role } : {}) };
+        if (options.printSql) {
+            const plan = await planConsoleRole(run, request);
+            statements = plan.statements;
+            user = plan.user;
+        }
+        else {
+            try {
+                const plan = await provisionConsoleRole(run, request);
+                statements = plan.statements;
+                user = plan.user;
+            }
+            catch (error) {
+                // The message never carries the new password (provisionConsoleRole scrubs; scrub again here).
+                throw new ConsoleRoleError('denied', scrubSecret(`主账号无法创建受限账号（${error instanceof Error ? error.message : String(error)}）；改用 zhin db console-role --print-sql 把 SQL 交给 DBA 执行`, [password]));
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof ConsoleRoleError)
+            throw error;
+        throw new ConsoleRoleError('unavailable', scrubSecret(error instanceof Error ? error.message : String(error), [password]));
+    }
+    finally {
+        await main.stop().catch(() => undefined);
+    }
+    // The password lives only in .env (ADR 0057); the config references it.
+    await writeEnvFile(projectRoot, '.env', upsertDotenv(await readEnvFile(projectRoot, '.env'), {
+        [CONSOLE_ROLE_USER_ENV]: user,
+        [CONSOLE_ROLE_PASSWORD_ENV]: password,
+    }));
+    const store = new ConsoleConfigurationStore({
+        projectRoot,
+        document: createConfigDocument(join(projectRoot, findConfigFile(projectRoot) ?? DEFAULT_ROOT_CONFIG_FILE_NAME)),
+    });
+    const document = await store.readDocument();
+    const block = document.database && typeof document.database === 'object' && !Array.isArray(document.database)
+        ? document.database
+        : { dialect };
+    await store.setKey('database', { ...block, console: { ...ENV_REFERENCE } });
+    return Object.freeze({
+        dialect,
+        user,
+        provisioned: !options.printSql,
+        // PostgreSQL statements carry a SCRAM verifier, never the password; MySQL's are shown with a placeholder.
+        statements: Object.freeze(statements.map(statement => scrubSecret(statement, [password]).split('[redacted]').join(CONSOLE_ROLE_PASSWORD_PLACEHOLDER))),
+        envFile: '.env',
+    });
+}
+/** The default role name of a project (what `zhin db console-role` creates). */
+export function defaultConsoleRoleName(projectRoot) {
+    return consoleRoleName(projectRoot);
+}

package/lib/database/gateway-store.d.ts

@@ -0,0 +1,43 @@
+import type { DatabaseHostModel } from '@zhin.js/plugin-runtime';
+import { type ProjectDatabaseTransaction } from './project-database.js';
+/** Project-relative path of the gateway store. */
+export declare const GATEWAY_STORE_FILE: string;
+/** Key / value table of the gateway store (`schema_version`, `legacy_import`). */
+export declare const GATEWAY_META_TABLE = "gateway_meta";
+/** Schema version written to `gateway_meta.schema_version`. */
+export declare const GATEWAY_STORE_SCHEMA_VERSION = 1;
+export interface GatewayStore {
+    /** Absolute path of `gateway.db`. */
+    readonly filename: string;
+    /**
+     * Random id of this store (`gateway_meta.store_id`), also written to the marker in the project
+     * database (ADR 0059 §3 修订): a new or different gateway.db is noticed instead of reopening setup.
+     */
+    readonly storeId: string;
+    readonly started: boolean;
+    readonly models: {
+        get(name: string): DatabaseHostModel | undefined;
+    };
+    /** JSON value of a `gateway_meta` key, or undefined. */
+    getMeta<T = unknown>(key: string, trx?: ProjectDatabaseTransaction): Promise<T | undefined>;
+    setMeta(key: string, value: unknown, trx?: ProjectDatabaseTransaction): Promise<void>;
+    deleteMeta(key: string, trx?: ProjectDatabaseTransaction): Promise<void>;
+    /** A write transaction (`BEGIN IMMEDIATE`: also the lock between the gateway and the CLI). */
+    transaction<T>(callback: (trx: ProjectDatabaseTransaction) => Promise<T>): Promise<T>;
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<T>;
+    /** Rows in each of the access-control tables. */
+    counts(trx?: ProjectDatabaseTransaction): Promise<Readonly<Record<string, number>>>;
+    /** A consistent copy of `gateway.db` (0600). */
+    backupTo(destination: string): Promise<void>;
+    close(): Promise<void>;
+}
+export interface OpenGatewayStoreOptions {
+    /** Overrides the file (tests). Default `<projectRoot>/.zhin/gateway.db`. */
+    readonly filename?: string;
+    /** `SQLITE_BUSY` async retry budget (default {@link GATEWAY_SQLITE_BUSY_RETRY_MS}). */
+    readonly busyRetryMs?: number;
+}
+/** `<projectRoot>/.zhin/gateway.db`. */
+export declare function gatewayStorePath(projectRoot: string): string;
+/** Opens (creating if needed) the gateway store with its tables. */
+export declare function openGatewayStore(projectRoot: string, options?: OpenGatewayStoreOptions): Promise<GatewayStore>;

package/lib/database/gateway-store.js

@@ -0,0 +1,90 @@
+/**
+ * The gateway's own store `.zhin/gateway.db` (ADR 0059 §1): the six Console access-control
+ * tables (`IAM_TABLES`) and `gateway_meta`, in SQLite whatever dialect the project database
+ * uses. Owner-only (0600, `-wal` / `-shm` included).
+ *
+ * Opened only by the gateway, by `zhin console …` while no gateway runs, and by a standalone
+ * instance (`zhin start --standalone`, development and tests only: there the instance process
+ * holds both connections, so there is no process isolation). A supervised instance never opens
+ * it, and its own SQLite connection refuses `ATTACH` (`denyAttach`).
+ */
+import { randomBytes } from 'node:crypto';
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { defineConsoleIamTables, IAM_TABLES } from '../iam/tables.js';
+import { GATEWAY_SQLITE_BUSY_RETRY_MS, ProjectDatabase } from './project-database.js';
+/** Project-relative path of the gateway store. */
+export const GATEWAY_STORE_FILE = join('.zhin', 'gateway.db');
+/** Key / value table of the gateway store (`schema_version`, `legacy_import`). */
+export const GATEWAY_META_TABLE = 'gateway_meta';
+/** Schema version written to `gateway_meta.schema_version`. */
+export const GATEWAY_STORE_SCHEMA_VERSION = 1;
+const META_DEFINITION = Object.freeze({
+    key: { type: 'text', length: 64, primary: true, nullable: false },
+    value: { type: 'text', nullable: false },
+});
+/** `<projectRoot>/.zhin/gateway.db`. */
+export function gatewayStorePath(projectRoot) {
+    return join(projectRoot, GATEWAY_STORE_FILE);
+}
+function restrict(file) {
+    if (process.platform === 'win32')
+        return;
+    if (existsSync(file))
+        chmodSync(file, 0o600);
+}
+/** Opens (creating if needed) the gateway store with its tables. */
+export async function openGatewayStore(projectRoot, options = {}) {
+    const filename = options.filename ?? gatewayStorePath(projectRoot);
+    mkdirSync(dirname(filename), { recursive: true });
+    // Create the file owner-only before SQLite does (it would follow the umask); SQLite gives the
+    // -wal / -shm files the mode of the database file.
+    if (!existsSync(filename))
+        closeSync(openSync(filename, 'a', 0o600));
+    restrict(filename);
+    const database = new ProjectDatabase({ dialect: 'sqlite', filename, busyRetryMs: options.busyRetryMs ?? GATEWAY_SQLITE_BUSY_RETRY_MS });
+    defineConsoleIamTables(database);
+    database.define(GATEWAY_META_TABLE, META_DEFINITION);
+    await database.start();
+    for (const suffix of ['', '-wal', '-shm'])
+        restrict(`${filename}${suffix}`);
+    const run = (sql, params, trx) => (trx ? trx.query(sql, params) : database.query(sql, params));
+    let storeId = '';
+    const store = {
+        filename,
+        get storeId() { return storeId; },
+        get started() { return database.started; },
+        models: database.models,
+        async getMeta(key, trx) {
+            const rows = await run(`SELECT value FROM ${GATEWAY_META_TABLE} WHERE key = ?`, [key], trx);
+            return rows[0] ? JSON.parse(rows[0].value) : undefined;
+        },
+        async setMeta(key, value, trx) {
+            await run(`INSERT INTO ${GATEWAY_META_TABLE} (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value`, [key, JSON.stringify(value)], trx);
+        },
+        async deleteMeta(key, trx) {
+            await run(`DELETE FROM ${GATEWAY_META_TABLE} WHERE key = ?`, [key], trx);
+        },
+        transaction: callback => database.transaction(callback),
+        query: (sql, params) => database.query(sql, params),
+        async counts(trx) {
+            const out = {};
+            for (const table of Object.values(IAM_TABLES)) {
+                const [row] = await run(`SELECT count(*) AS n FROM "${table}"`, [], trx);
+                out[table] = Number(row?.n ?? 0);
+            }
+            return Object.freeze(out);
+        },
+        backupTo: destination => database.backupTo(destination),
+        close: () => database.stop(),
+    };
+    if (await store.getMeta('schema_version') === undefined)
+        await store.setMeta('schema_version', GATEWAY_STORE_SCHEMA_VERSION);
+    storeId = await store.getMeta('store_id') ?? '';
+    if (!storeId) {
+        // Insert-if-absent: two processes opening a new store agree on one id.
+        await database.query(`INSERT INTO ${GATEWAY_META_TABLE} (key, value) VALUES ('store_id', ?) ON CONFLICT(key) DO NOTHING`, [JSON.stringify(randomBytes(16).toString('hex'))]);
+        storeId = await store.getMeta('store_id') ?? '';
+    }
+    return Object.freeze(store);
+}

package/lib/database/index.d.ts

@@ -1,2 +1,4 @@
 export * from './config.js';
+export * from './gateway-store.js';
 export * from './project-database.js';
+export * from './console-role.js';

package/lib/database/index.js

@@ -1,2 +1,4 @@
 export * from './config.js';
+export * from './gateway-store.js';
 export * from './project-database.js';
+export * from './console-role.js';

package/lib/database/project-database.d.ts

@@ -14,6 +14,21 @@ export declare const DATABASE_BUSY_RETRY_AFTER_SECONDS = 2;
 export declare function isDatabaseBusyError(error: unknown): boolean;
 /** `503 { code: 'database_busy' }` with `Retry-After`. */
 export declare function databaseBusyResponse(extra?: Readonly<Record<string, unknown>>): Response;
+/** One statement inside {@link ProjectDatabase.transaction}. */
+export interface ProjectDatabaseTransaction {
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<T>;
+}
+/** The gateway's marker in the project database. */
+export interface StoreMarker {
+    readonly storeId: string;
+    readonly migratedAt: number;
+}
+/** Rows keyed by table name. */
+export type TableRows = Readonly<Record<string, readonly Record<string, unknown>[]>>;
+/** Rows read per batch by {@link ProjectDatabase.readSnapshot}. */
+export declare const SNAPSHOT_BATCH_SIZE = 500;
+/** A quoted table name for `dialect`. */
+export declare function quoteTableName(dialect: string, name: string): string;
 /** One database connection; tables are defined before {@link start}. */
 export declare class ProjectDatabase {
     #private;
@@ -26,6 +41,36 @@ export declare class ProjectDatabase {
     readonly models: Readonly<{
         get: (name: string) => DatabaseHostModel | undefined;
     }>;
+    /** Whether raw SQL / transactions are available (SQLite, MySQL, PostgreSQL). */
+    get relational(): boolean;
+    /** One raw statement (gateway-internal: the gateway store, the legacy import and its revert). */
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<T>;
+    /** A transaction (SQLite write transactions are `BEGIN IMMEDIATE`). */
+    transaction<T>(callback: (trx: ProjectDatabaseTransaction) => Promise<T>, options?: {
+        readOnly?: boolean;
+        repeatableRead?: boolean;
+    }): Promise<T>;
+    /** SQLite: a consistent copy of the file at `destination` (0600). */
+    backupTo(destination: string): Promise<void>;
+    /** Which of `names` exist as tables (collections), read from the system catalog without defining them. */
+    tableExists(names: readonly string[]): Promise<string[]>;
+    /**
+     * All rows of `tables`, read in batches of {@link SNAPSHOT_BATCH_SIZE} ordered by `id`. SQL
+     * dialects read inside one read-only repeatable-read transaction (one snapshot); MongoDB reads
+     * the collections one after another.
+     */
+    readSnapshot(tables: readonly string[]): Promise<TableRows>;
+    /**
+     * Drops `tables` if they exist: in one transaction on SQLite / PostgreSQL, one by one on MySQL
+     * (DDL commits implicitly) and MongoDB, where an interrupted run resumes with the rest.
+     */
+    dropTables(tables: readonly string[]): Promise<void>;
+    /** The gateway's marker (ADR 0059 §3 修订): which gateway.db holds the Console accounts, or undefined. */
+    readStoreMarker(): Promise<StoreMarker | undefined>;
+    /** Writes (replaces) the marker. */
+    writeStoreMarker(marker: StoreMarker): Promise<void>;
+    /** Removes the marker (revert to a version without it). */
+    deleteStoreMarker(): Promise<void>;
     start(): Promise<void>;
     stop(): Promise<void>;
 }