@zhin.js/gateway 0.0.1-bootstrap.0 → 1.1.2

package/lib/config/plugin-schema-catalog.js

@@ -0,0 +1,262 @@
+import { readFile, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createConfigDocument, HOST_CONFIG_KEYS, readApplicationPluginDeclaration, HOST_CONFIG_SCHEMA, ManifestValidationError, NodePackageResolver, PackageResolutionError, } from '@zhin.js/runtime';
+import { findConfigFile } from '../project/config-file.js';
+import { isConsoleSchemaJson, jsonSchemaToConsoleSchema } from './console-schema.js';
+const HOST_CONFIG_KEY_SET = new Set(HOST_CONFIG_KEYS);
+/** Resolves schemas using the same package roots and declarations as Runtime. */
+export class PluginSchemaCatalog {
+    #projectRoot;
+    #declarations;
+    constructor(projectRoot, declarations) {
+        this.#projectRoot = projectRoot;
+        this.#declarations = declarations;
+    }
+    async read(pluginName, document) {
+        if (!pluginName)
+            return null;
+        return this.#read(pluginName, () => NodePackageResolver.create(this.#projectRoot), await this.#declarations?.(), false, document);
+    }
+    async readJson(pluginName, document) {
+        return (await this.#read(pluginName, () => NodePackageResolver.create(this.#projectRoot), await this.#declarations?.(), true, document));
+    }
+    /**
+     * Raw JSON schemas for several keys sharing one resolver and one declaration read.
+     * A key whose schema cannot be read maps to its `Error`, so callers can fail closed per key.
+     */
+    async readJsonMany(keys, document) {
+        const list = [...keys];
+        let declarations;
+        try {
+            declarations = await this.#declarations?.();
+        }
+        catch (error) {
+            const failure = error instanceof Error ? error : new Error(String(error));
+            return new Map(list.map(key => [key, failure]));
+        }
+        let resolver;
+        return new Map(await Promise.all(list.map(async (key) => {
+            try {
+                const schema = await this.#read(key, () => resolver ??= NodePackageResolver.create(this.#projectRoot), declarations, true, document);
+                return [key, schema];
+            }
+            catch (error) {
+                return [key, error instanceof Error ? error : new Error(String(error))];
+            }
+        })));
+    }
+    /**
+     * Form schema of an installed plugin package that no instance declares yet (ADR 0053 §2 step 4):
+     * the package must be a production dependency (`dependencies` / `optionalDependencies`) of the
+     * project and a Plugin package. Returns the declared-instance form shape plus `declared: false`,
+     * `null` when such a package ships no `schema.json`, and `undefined` when `packageName` is not
+     * such a package (declared, not a dependency, not installed, not a Plugin, or not a package name).
+     */
+    async readUndeclared(packageName, currentDocument) {
+        if (HOST_CONFIG_KEY_SET.has(packageName) || packageName === 'root'
+            || !/^(?:@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/u.test(packageName))
+            return undefined;
+        let target;
+        try {
+            const packages = await NodePackageResolver.create(this.#projectRoot);
+            const root = await packages.root(this.#projectRoot);
+            const file = findConfigFile(this.#projectRoot);
+            const document = currentDocument ?? (file ? (await createConfigDocument(join(this.#projectRoot, file)).read()).document : {});
+            const declaration = readApplicationPluginDeclaration(document);
+            if (declaration.version !== 2)
+                return undefined;
+            if (declaration.instances.some(item => item.instanceKey === packageName || item.package === packageName))
+                return undefined;
+            const manifest = root.packageJson;
+            if (!Object.hasOwn(manifest.dependencies ?? {}, packageName)
+                && !Object.hasOwn(manifest.optionalDependencies ?? {}, packageName))
+                return undefined;
+            try {
+                target = await resolveReference(packages, root, { package: packageName, instanceKey: packageName });
+            }
+            catch (error) {
+                // A dependency without a Zhin manifest is a plain library, not an undeclared plugin.
+                if (error instanceof ManifestValidationError)
+                    return undefined;
+                throw error;
+            }
+            // A declaration through another reference (local path, alias) that resolves to the same
+            // package root already declares this package.
+            for (const item of declaration.instances) {
+                const declared = await resolveReference(packages, root, item).catch(() => undefined);
+                if (declared && target && declared.root === target.root)
+                    return undefined;
+            }
+        }
+        catch (error) {
+            throw new Error(`Cannot resolve schema for ${packageName}: invalid or unavailable Plugin manifest`, { cause: error });
+        }
+        if (!target)
+            return undefined;
+        const schema = (await this.#declarations?.())?.get(target.root) ?? await readOwnSchema(target.root, packageName, true);
+        if (!schema)
+            return null;
+        assertSchemaStructure(schema, `config declaration for ${packageName}`);
+        const form = jsonSchemaToConsoleSchema(schema);
+        return form ? Object.freeze({ ...form, declared: false }) : null;
+    }
+    async readAll(keys, document) {
+        let resolver;
+        const declarations = await this.#declarations?.();
+        if (!document) {
+            const file = findConfigFile(this.#projectRoot);
+            if (file)
+                document = (await createConfigDocument(join(this.#projectRoot, file)).read()).document;
+        }
+        const entries = await Promise.all([...keys].map(async (key) => [
+            key,
+            await this.#read(key, () => resolver ??= NodePackageResolver.create(this.#projectRoot), declarations, false, document),
+        ]));
+        return Object.fromEntries(entries.filter((entry) => entry[1] != null));
+    }
+    async #read(pluginName, resolver, declarations, rawSchema = false, currentDocument) {
+        if (HOST_CONFIG_KEY_SET.has(pluginName)) {
+            // Host sections share the Runtime schema and its local definition scope.
+            // This is only a display projection; Runtime remains the config validator.
+            const raw = pluginName === 'plugin'
+                ? declarations?.get(await realpath(this.#projectRoot)) ?? await readOwnSchema(this.#projectRoot, 'plugin', !rawSchema)
+                : HOST_CONFIG_SCHEMA.properties[pluginName];
+            if (rawSchema)
+                return raw && pluginName !== 'plugin'
+                    ? { ...raw, $defs: HOST_CONFIG_SCHEMA.$defs } : raw ?? null;
+            if (raw && pluginName === 'plugin')
+                assertSchemaStructure(raw, 'config declaration for plugin');
+            return jsonSchemaToConsoleSchema(raw && pluginName !== 'plugin' ? { ...raw, $defs: HOST_CONFIG_SCHEMA.$defs } : raw);
+        }
+        if (!/^(?:@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/u.test(pluginName)
+            && !pluginName.split('/').every((key) => /^[a-z0-9][a-z0-9-]*$/u.test(key))) {
+            return null;
+        }
+        let target;
+        try {
+            const packages = await resolver();
+            const root = await packages.root(this.#projectRoot);
+            const file = findConfigFile(this.#projectRoot);
+            const document = currentDocument ?? (file ? (await createConfigDocument(join(this.#projectRoot, file)).read()).document : {});
+            const declaration = readApplicationPluginDeclaration(document);
+            if (declaration.version === 2) {
+                const name = pluginName.startsWith('root/') ? pluginName.slice(5) : pluginName;
+                const exact = declaration.instances.find(item => item.instanceKey === name);
+                const matches = exact ? [exact] : declaration.instances.filter(item => item.package === pluginName);
+                if (matches.length > 1)
+                    throw new Error('此包存在多个插件实例，请使用精确 instanceKey');
+                if (matches[0])
+                    target = await resolveReference(packages, root, matches[0]);
+                else if (pluginName === 'root')
+                    target = root;
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('多个插件实例'))
+                throw error;
+            throw new Error(`Cannot resolve schema for ${pluginName}: invalid or unavailable Plugin manifest`, { cause: error });
+        }
+        if (!target)
+            return null;
+        const schema = declarations?.get(target.root) ?? await readOwnSchema(target.root, pluginName, !rawSchema);
+        if (rawSchema)
+            return schema;
+        if (schema)
+            assertSchemaStructure(schema, `config declaration for ${pluginName}`);
+        return jsonSchemaToConsoleSchema(schema);
+    }
+}
+async function resolveReference(resolver, owner, reference) {
+    try {
+        const pkg = await resolver.resolve(reference.package, owner);
+        return pkg.packageJson.zhin.type === 'plugin' ? pkg : undefined;
+    }
+    catch (error) {
+        if (error instanceof PackageResolutionError)
+            return undefined;
+        throw error;
+    }
+}
+/** Missing schemas have no form; malformed schemas must not masquerade as missing. */
+async function readOwnSchema(root, name, forForm = true) {
+    let text;
+    try {
+        text = await readFile(join(root, 'schema.json'), 'utf8');
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return null;
+        throw new Error(`Cannot read schema.json for ${name}`, { cause: error });
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`Invalid JSON in schema.json for ${name}`);
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`schema.json for ${name} must contain a JSON Schema object`);
+    }
+    const schema = value;
+    if (schema.type !== undefined && schema.type !== 'object') {
+        throw new Error(`schema.json for ${name} root schema type must be object`);
+    }
+    if (schema.properties !== undefined
+        && (!schema.properties || typeof schema.properties !== 'object' || Array.isArray(schema.properties))) {
+        throw new Error(`schema.json for ${name} properties must be an object`);
+    }
+    if (forForm)
+        assertSchemaStructure(schema, `schema.json for ${name}`);
+    return schema;
+}
+/** Reject malformed child definitions before the form converter can silently omit them. */
+function assertSchemaStructure(value, location) {
+    if (typeof value === 'boolean')
+        return;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`${location} must contain a supported schema object`);
+    }
+    const schema = value;
+    if (schema.$ref !== undefined && typeof schema.$ref !== 'string')
+        throw new Error(`${location}.$ref must be a string`);
+    if (schema.type !== undefined && !(typeof schema.type === 'string' || Array.isArray(schema.type) && schema.type.every(type => typeof type === 'string')))
+        throw new Error(`${location}.type must be a string or string array`);
+    if (schema.required !== undefined) {
+        const nativeFlag = typeof schema.required === 'boolean' && isConsoleSchemaJson(schema);
+        if (!nativeFlag && (!Array.isArray(schema.required)
+            || !schema.required.every((key) => typeof key === 'string')
+            || new Set(schema.required).size !== schema.required.length)) {
+            throw new Error(`${location}.required must be a unique string array or a native Schema boolean`);
+        }
+    }
+    for (const key of ['properties', '$defs', 'definitions', 'object', 'patternProperties', 'dependentSchemas']) {
+        const children = schema[key];
+        if (children === undefined)
+            continue;
+        if (!children || typeof children !== 'object' || Array.isArray(children)) {
+            throw new Error(`${location}.${key} must be an object`);
+        }
+        for (const [name, child] of Object.entries(children)) {
+            assertSchemaStructure(child, `${location}.${key}.${name}`);
+        }
+    }
+    for (const key of ['items', 'inner', 'additionalProperties', 'additional', 'additionalItems', 'contains', 'not', 'if', 'then', 'else']) {
+        const child = schema[key];
+        if (child === undefined || (key === 'additionalProperties' && typeof child === 'boolean'))
+            continue;
+        if (key === 'items' && Array.isArray(child)) {
+            child.forEach((item, index) => assertSchemaStructure(item, `${location}.items[${index}]`));
+            continue;
+        }
+        assertSchemaStructure(child, `${location}.${key}`);
+    }
+    for (const key of ['list', 'anyOf', 'oneOf', 'allOf', 'prefixItems']) {
+        const children = schema[key];
+        if (children === undefined)
+            continue;
+        if (!Array.isArray(children) || ['anyOf', 'oneOf', 'allOf'].includes(key) && children.length === 0)
+            throw new Error(`${location}.${key} must be a non-empty schema array`);
+        children.forEach((child, index) => assertSchemaStructure(child, `${location}.${key}[${index}]`));
+    }
+}

package/lib/config.d.ts

@@ -0,0 +1,13 @@
+/** `@zhin.js/gateway/config` — raw project configuration and `.env` access. */
+export * from './config/ai-config-loader.js';
+export * from './config/configuration.js';
+export * from './config/configuration-chat-policy.js';
+export * from './config/configuration-patch.js';
+export * from './config/configuration-path.js';
+export * from './config/configuration-projection.js';
+export * from './config/configuration-redaction.js';
+export * from './config/console-schema.js';
+export * from './config/environment-files.js';
+export * from './config/literal-secrets.js';
+export * from './config/plugin-package-map.js';
+export * from './config/plugin-schema-catalog.js';

package/lib/config.js

@@ -0,0 +1,13 @@
+/** `@zhin.js/gateway/config` — raw project configuration and `.env` access. */
+export * from './config/ai-config-loader.js';
+export * from './config/configuration.js';
+export * from './config/configuration-chat-policy.js';
+export * from './config/configuration-patch.js';
+export * from './config/configuration-path.js';
+export * from './config/configuration-projection.js';
+export * from './config/configuration-redaction.js';
+export * from './config/console-schema.js';
+export * from './config/environment-files.js';
+export * from './config/literal-secrets.js';
+export * from './config/plugin-package-map.js';
+export * from './config/plugin-schema-catalog.js';

package/lib/database/config.d.ts

@@ -0,0 +1,22 @@
+export type ProjectDatabaseConfig = {
+    readonly dialect: string;
+} & Readonly<Record<string, unknown>>;
+/** Project-relative default when no `database` block is configured. */
+export declare const DEFAULT_PROJECT_DATABASE_FILE: string;
+/** Validates an expanded `database` block (port of `normalizeDatabaseHostConfig`). */
+export declare function normalizeProjectDatabaseConfig(input: ProjectDatabaseConfig): ProjectDatabaseConfig;
+/**
+ * Resolves the expanded root config document's `database` block. A relative SQLite file is
+ * anchored at the project root (the instance runs with the project root as cwd, so both
+ * processes open the same file).
+ */
+export declare function resolveProjectDatabaseConfig(projectRoot: string, document: unknown): Promise<ProjectDatabaseConfig>;
+/**
+ * The root config document with `${…}` expanded against process env and the project `.env`
+ * layers of `environment` (missing variables become empty, as in the instance). Only the gateway's
+ * own blocks are read from it (`database`, `console.terminal`): plugin declarations are not
+ * validated here, so a config the instance rejects still leaves the Console reachable.
+ */
+export declare function loadExpandedProjectConfig(projectRoot: string, environment?: string): Promise<Readonly<Record<string, unknown>>>;
+/** {@link resolveProjectDatabaseConfig} over {@link loadExpandedProjectConfig}. */
+export declare function loadProjectDatabaseConfig(projectRoot: string, environment?: string): Promise<ProjectDatabaseConfig>;

package/lib/database/config.js

@@ -0,0 +1,159 @@
+/**
+ * The project `database` block as the gateway resolves it (ADR 0054 §7): the same file and
+ * driver settings as the instance's `resolveDatabaseConfig` (`@zhin.js/core`), ported here so the
+ * gateway never imports IM layers. Keep the two in step.
+ */
+import { mkdir } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { expandEnvironmentValue } from '@zhin.js/plugin-runtime';
+import { createConfigDocument } from '@zhin.js/runtime';
+import { findConfigFile } from '../project/config-file.js';
+import { loadRuntimeEnvironmentLayers } from '../project/environment.js';
+/** Project-relative default when no `database` block is configured. */
+export const DEFAULT_PROJECT_DATABASE_FILE = join('.zhin', 'data.sqlite');
+const SUPPORTED_DIALECTS = new Set(['memory', 'mongodb', 'mysql', 'pg', 'redis', 'sqlite']);
+function configurationError(path, expectation, envExample) {
+    const envHint = envExample
+        ? `若这里引用环境变量，请在项目根目录 .env 中设置 ${envExample}。`
+        : '若这里引用环境变量，请检查项目根目录 .env 中的对应变量。';
+    return new TypeError(`数据库配置 ${path} ${expectation}。${envHint}也可运行 \`zhin setup --database\` 重新配置。`);
+}
+function normalizePort(value, path, envExample) {
+    if (value === undefined)
+        return undefined;
+    const normalized = typeof value === 'number'
+        ? value
+        : typeof value === 'string' && /^\d+$/u.test(value.trim()) ? Number(value.trim()) : Number.NaN;
+    if (!Number.isInteger(normalized) || normalized < 1 || normalized > 65535) {
+        throw configurationError(path, '必须是 1-65535 的整数，当前值为空或无效', envExample);
+    }
+    return normalized;
+}
+function normalizeOptionalText(config, key, path, envExample) {
+    if (!(key in config))
+        return;
+    const value = config[key];
+    if (typeof value !== 'string' || value.trim() === '')
+        throw configurationError(path, '不能为空', envExample);
+    config[key] = value.trim();
+}
+function normalizeRequiredText(config, key, path, envExample) {
+    if (!(key in config))
+        config[key] = undefined;
+    normalizeOptionalText(config, key, path, envExample);
+}
+function normalizeRedisDatabase(value) {
+    if (value === undefined)
+        return undefined;
+    const normalized = typeof value === 'number'
+        ? value
+        : typeof value === 'string' && /^\d+$/u.test(value.trim()) ? Number(value.trim()) : Number.NaN;
+    if (!Number.isInteger(normalized) || normalized < 0) {
+        throw configurationError('database.database', '必须是大于或等于 0 的整数', 'REDIS_DB=0');
+    }
+    return normalized;
+}
+/** Validates an expanded `database` block (port of `normalizeDatabaseHostConfig`). */
+export function normalizeProjectDatabaseConfig(input) {
+    const dialect = input.dialect;
+    if (!SUPPORTED_DIALECTS.has(dialect)) {
+        throw new TypeError(`数据库配置 database.dialect 不支持 ${JSON.stringify(dialect)}；可选值为 sqlite、mysql、pg、mongodb、redis、memory。`);
+    }
+    const config = { ...input, dialect };
+    switch (dialect) {
+        case 'mysql':
+            normalizeOptionalText(config, 'host', 'database.host', 'DB_HOST=127.0.0.1');
+            normalizeOptionalText(config, 'user', 'database.user', 'DB_USER=root');
+            normalizeOptionalText(config, 'database', 'database.database', 'DB_DATABASE=zhin_bot');
+            normalizeOptionalText(config, 'uri', 'database.uri');
+            config.port = normalizePort(config.port, 'database.port', 'DB_PORT=3306');
+            if (config.port === undefined)
+                delete config.port;
+            break;
+        case 'pg':
+            normalizeOptionalText(config, 'host', 'database.host', 'DB_HOST=127.0.0.1');
+            normalizeOptionalText(config, 'user', 'database.user', 'DB_USER=postgres');
+            normalizeOptionalText(config, 'database', 'database.database', 'DB_DATABASE=zhin_bot');
+            normalizeOptionalText(config, 'connectionString', 'database.connectionString');
+            config.port = normalizePort(config.port, 'database.port', 'DB_PORT=5432');
+            if (config.port === undefined)
+                delete config.port;
+            break;
+        case 'mongodb':
+            normalizeRequiredText(config, 'url', 'database.url', 'DB_URL=mongodb://127.0.0.1:27017');
+            normalizeRequiredText(config, 'dbName', 'database.dbName', 'DB_NAME=zhin_bot');
+            if (!/^mongodb(?:\+srv)?:\/\//u.test(String(config.url)))
+                throw configurationError('database.url', '必须使用 mongodb:// 或 mongodb+srv://');
+            break;
+        case 'redis': {
+            normalizeOptionalText(config, 'url', 'database.url', 'REDIS_URL=redis://127.0.0.1:6379');
+            if (config.socket !== undefined) {
+                if (!config.socket || typeof config.socket !== 'object' || Array.isArray(config.socket))
+                    throw configurationError('database.socket', '必须是对象');
+                const socket = { ...config.socket };
+                normalizeOptionalText(socket, 'host', 'database.socket.host', 'REDIS_HOST=127.0.0.1');
+                socket.port = normalizePort(socket.port, 'database.socket.port', 'REDIS_PORT=6379');
+                if (socket.port === undefined)
+                    delete socket.port;
+                config.socket = Object.freeze(socket);
+            }
+            config.database = normalizeRedisDatabase(config.database);
+            if (config.database === undefined)
+                delete config.database;
+            break;
+        }
+        case 'sqlite':
+            if (config.filename === undefined)
+                config.filename = './data/bot.db';
+            normalizeOptionalText(config, 'filename', 'database.filename');
+            break;
+        case 'memory':
+            break;
+    }
+    return Object.freeze(config);
+}
+/**
+ * Resolves the expanded root config document's `database` block. A relative SQLite file is
+ * anchored at the project root (the instance runs with the project root as cwd, so both
+ * processes open the same file).
+ */
+export async function resolveProjectDatabaseConfig(projectRoot, document) {
+    const configured = document && typeof document === 'object' ? document.database : undefined;
+    if (configured && typeof configured === 'object' && !Array.isArray(configured)) {
+        const value = configured;
+        const normalized = normalizeProjectDatabaseConfig({ ...value, dialect: typeof value.dialect === 'string' ? value.dialect : 'sqlite' });
+        if (normalized.dialect === 'sqlite' && typeof normalized.filename === 'string' && !isSqliteMemory(normalized.filename) && !isAbsolute(normalized.filename)) {
+            return Object.freeze({ ...normalized, filename: resolve(projectRoot, normalized.filename) });
+        }
+        return normalized;
+    }
+    const filename = join(projectRoot, DEFAULT_PROJECT_DATABASE_FILE);
+    await mkdir(dirname(filename), { recursive: true });
+    return Object.freeze({ dialect: 'sqlite', filename });
+}
+/**
+ * The root config document with `${…}` expanded against process env and the project `.env`
+ * layers of `environment` (missing variables become empty, as in the instance). Only the gateway's
+ * own blocks are read from it (`database`, `console.terminal`): plugin declarations are not
+ * validated here, so a config the instance rejects still leaves the Console reachable.
+ */
+export async function loadExpandedProjectConfig(projectRoot, environment = 'development') {
+    const file = findConfigFile(projectRoot);
+    if (!file)
+        return Object.freeze({});
+    const [document, layers] = await Promise.all([
+        createConfigDocument(join(projectRoot, file)).read().then((snapshot) => snapshot.document),
+        loadRuntimeEnvironmentLayers(projectRoot, environment),
+    ]);
+    if (!document || typeof document !== 'object' || Array.isArray(document))
+        return Object.freeze({});
+    const overlay = layers.environments?.[environment];
+    return expandEnvironmentValue(document, (key) => overlay?.[key] ?? layers.base?.[key] ?? process.env[key]);
+}
+/** {@link resolveProjectDatabaseConfig} over {@link loadExpandedProjectConfig}. */
+export async function loadProjectDatabaseConfig(projectRoot, environment = 'development') {
+    return resolveProjectDatabaseConfig(projectRoot, await loadExpandedProjectConfig(projectRoot, environment));
+}
+function isSqliteMemory(filename) {
+    return filename === ':memory:' || filename.startsWith('file::memory:');
+}

package/lib/database/index.d.ts

@@ -0,0 +1,2 @@
+export * from './config.js';
+export * from './project-database.js';

package/lib/database/index.js

@@ -0,0 +1,2 @@
+export * from './config.js';
+export * from './project-database.js';

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

@@ -0,0 +1,31 @@
+import type { DatabaseHostModel } from '@zhin.js/plugin-runtime';
+import type { ProjectDatabaseConfig } from './config.js';
+/**
+ * How long a gateway statement retries `SQLITE_BUSY` while the instance holds the write lock
+ * (`busyRetryMs` in `@zhin.js/database`). The retry backs off asynchronously, so the gateway's
+ * event loop keeps serving requests during the wait; a synchronous `busy_timeout` would stall
+ * every request for as long as an instance transaction runs. Past the budget the request
+ * answers `503 database_busy` ({@link isDatabaseBusyError}).
+ */
+export declare const GATEWAY_SQLITE_BUSY_RETRY_MS = 5000;
+/** Seconds a `503 database_busy` asks the client to wait. */
+export declare const DATABASE_BUSY_RETRY_AFTER_SECONDS = 2;
+/** The database stayed locked by another connection for the whole retry budget. */
+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 database connection; tables are defined before {@link start}. */
+export declare class ProjectDatabase {
+    #private;
+    readonly config: ProjectDatabaseConfig;
+    constructor(config: ProjectDatabaseConfig);
+    get dialect(): string;
+    get started(): boolean;
+    define(name: string, definition: Record<string, unknown>): void;
+    tables(): readonly string[];
+    readonly models: Readonly<{
+        get: (name: string) => DatabaseHostModel | undefined;
+    }>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}

package/lib/database/project-database.js

@@ -0,0 +1,130 @@
+/**
+ * The gateway's own connection to the project database (ADR 0054 §7). It defines and serves only
+ * the tables the gateway owns (`console_*`, ADR 0049); the instance opens the same database for
+ * everything else. SQLite runs in WAL mode (`@zhin.js/database`), so both processes can hold the
+ * file open.
+ */
+import { isSqliteBusyError, Registry } from '@zhin.js/database';
+/**
+ * How long a gateway statement retries `SQLITE_BUSY` while the instance holds the write lock
+ * (`busyRetryMs` in `@zhin.js/database`). The retry backs off asynchronously, so the gateway's
+ * event loop keeps serving requests during the wait; a synchronous `busy_timeout` would stall
+ * every request for as long as an instance transaction runs. Past the budget the request
+ * answers `503 database_busy` ({@link isDatabaseBusyError}).
+ */
+export const GATEWAY_SQLITE_BUSY_RETRY_MS = 5_000;
+/** Seconds a `503 database_busy` asks the client to wait. */
+export const DATABASE_BUSY_RETRY_AFTER_SECONDS = 2;
+/** The database stayed locked by another connection for the whole retry budget. */
+export function isDatabaseBusyError(error) {
+    for (let current = error, depth = 0; current && depth < 4; depth += 1) {
+        if (isSqliteBusyError(current))
+            return true;
+        current = current.cause;
+    }
+    return false;
+}
+/** `503 { code: 'database_busy' }` with `Retry-After`. */
+export function databaseBusyResponse(extra = {}) {
+    return new Response(JSON.stringify({
+        success: false,
+        code: 'database_busy',
+        error: '数据库正忙，请稍后重试',
+        ...extra,
+    }), {
+        status: 503,
+        headers: {
+            'content-type': 'application/json; charset=utf-8',
+            'cache-control': 'no-store',
+            'retry-after': String(DATABASE_BUSY_RETRY_AFTER_SECONDS),
+        },
+    });
+}
+function wrapModel(model) {
+    return Object.freeze({
+        select: (...fields) => {
+            if (fields.includes('*'))
+                throw new TypeError('select() requires explicit column names');
+            const selection = model.select(...fields);
+            const chain = {
+                where: (query) => { selection.where(query); return chain; },
+                orderBy: (field, direction) => { selection.orderBy?.(field, direction); return chain; },
+                limit: (count) => { selection.limit?.(count); return chain; },
+                then: (onfulfilled, onrejected) => Promise.resolve(selection).then(onfulfilled, onrejected),
+            };
+            return chain;
+        },
+        insert: (row) => Promise.resolve(model.insert(row)),
+        delete: () => ({ where: (query) => Promise.resolve(model.delete(query)) }),
+        update: (patch) => ({ where: (query) => Promise.resolve(model.update(patch).where(query)) }),
+    });
+}
+/** One database connection; tables are defined before {@link start}. */
+export class ProjectDatabase {
+    config;
+    #db;
+    #tables = new Set();
+    #wrapped = new Map();
+    #started = false;
+    constructor(config) {
+        this.config = config;
+        const { dialect, ...connection } = config;
+        // No synchronous busy_timeout: it would block the gateway's event loop (ADR 0054 §7).
+        const options = dialect === 'sqlite' && connection.busyRetryMs === undefined
+            ? { ...connection, busyRetryMs: GATEWAY_SQLITE_BUSY_RETRY_MS }
+            : connection;
+        this.#db = Registry.create(dialect, options);
+    }
+    get dialect() {
+        return this.config.dialect;
+    }
+    get started() {
+        return this.#started;
+    }
+    define(name, definition) {
+        if (this.#started)
+            throw new Error(`Project database already started; cannot define table ${name}`);
+        if (this.#tables.has(name))
+            return;
+        this.#tables.add(name);
+        this.#db.define(name, definition);
+    }
+    tables() {
+        return [...this.#tables];
+    }
+    models = Object.freeze({
+        get: (name) => {
+            if (!this.#started)
+                return undefined;
+            const cached = this.#wrapped.get(name);
+            if (cached)
+                return cached;
+            const raw = this.#db.models.get(name);
+            if (!raw)
+                return undefined;
+            const model = wrapModel(raw);
+            this.#wrapped.set(name, model);
+            return model;
+        },
+    });
+    async start() {
+        if (this.#started)
+            return;
+        try {
+            await this.#db.start();
+        }
+        catch (error) {
+            await this.#db.stop().catch(() => undefined);
+            throw error;
+        }
+        this.#started = true;
+        this.#wrapped.clear();
+    }
+    async stop() {
+        if (!this.#started)
+            return;
+        this.#started = false;
+        this.#wrapped.clear();
+        await this.#db.stop();
+    }
+}

package/lib/database.d.ts

@@ -0,0 +1,2 @@
+/** `@zhin.js/gateway/database` — the gateway's connection to the project database (ADR 0054 §7). */
+export * from './database/index.js';

package/lib/database.js

@@ -0,0 +1,2 @@
+/** `@zhin.js/gateway/database` — the gateway's connection to the project database (ADR 0054 §7). */
+export * from './database/index.js';