@zhin.js/gateway 1.1.2 → 1.2.0

package/lib/database/project-database.js

@@ -1,10 +1,11 @@
 /**
- * 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.
+ * A connection the gateway opens itself (ADR 0054 §7, ADR 0059): its own store
+ * `.zhin/gateway.db` (`openGatewayStore`), and — only while importing the Console tables an
+ * earlier version left in the project database, reverting that import, or testing a connection
+ * in the setup wizard — a short-lived connection to the project database. SQLite runs in WAL
+ * mode (`@zhin.js/database`), so several processes can hold a file open.
  */
-import { isSqliteBusyError, Registry } from '@zhin.js/database';
+import { GATEWAY_STORE_MARKER_TABLE, 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
@@ -40,6 +41,22 @@ export function databaseBusyResponse(extra = {}) {
         },
     });
 }
+function markerOf(row) {
+    return Object.freeze({ storeId: String(row.store_id ?? ''), migratedAt: Number(row.migrated_at ?? 0) });
+}
+const SQL_DIALECTS = new Set(['sqlite', 'mysql', 'pg']);
+/** Rows read per batch by {@link ProjectDatabase.readSnapshot}. */
+export const SNAPSHOT_BATCH_SIZE = 500;
+const BACKTICK = String.fromCharCode(96);
+/** A quoted table name for `dialect`. */
+export function quoteTableName(dialect, name) {
+    return dialect === 'mysql'
+        ? BACKTICK + name.split(BACKTICK).join(BACKTICK + BACKTICK) + BACKTICK
+        : `"${name.replace(/"/gu, '""')}"`;
+}
+function placeholder(dialect, index) {
+    return dialect === 'pg' ? `$${index}` : '?';
+}
 function wrapModel(model) {
     return Object.freeze({
         select: (...fields) => {
@@ -68,7 +85,8 @@ export class ProjectDatabase {
     #started = false;
     constructor(config) {
         this.config = config;
-        const { dialect, ...connection } = config;
+        // `console` (the restricted Console account, ADR 0059) and `denyAttach` (instance only) never reach the driver.
+        const { dialect, console: _console, denyAttach: _denyAttach, ...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 }
@@ -107,6 +125,194 @@ export class ProjectDatabase {
             return model;
         },
     });
+    /** Whether raw SQL / transactions are available (SQLite, MySQL, PostgreSQL). */
+    get relational() {
+        return SQL_DIALECTS.has(this.config.dialect);
+    }
+    #requireStarted() {
+        if (!this.#started)
+            throw new Error('Database is not connected');
+    }
+    #requireSql() {
+        this.#requireStarted();
+        if (!this.relational)
+            throw new Error(`Raw SQL is not supported by '${this.config.dialect}'`);
+    }
+    /** One raw statement (gateway-internal: the gateway store, the legacy import and its revert). */
+    async query(sql, params) {
+        this.#requireSql();
+        return this.#db.query(sql, params);
+    }
+    /** A transaction (SQLite write transactions are `BEGIN IMMEDIATE`). */
+    async transaction(callback, options) {
+        this.#requireSql();
+        return this.#db.transaction(trx => callback({ query: (sql, params) => trx.query(sql, params) }), {
+            ...(options?.readOnly ? { readOnly: true } : {}),
+            ...(options?.repeatableRead ? { isolationLevel: 'REPEATABLE_READ' } : {}),
+        });
+    }
+    /** SQLite: a consistent copy of the file at `destination` (0600). */
+    async backupTo(destination) {
+        this.#requireStarted();
+        if (this.config.dialect !== 'sqlite' || typeof this.#db.dialect?.backupTo !== 'function') {
+            throw new Error(`File backups need SQLite (current: ${this.config.dialect})`);
+        }
+        await this.#db.dialect.backupTo(destination);
+    }
+    /** Which of `names` exist as tables (collections), read from the system catalog without defining them. */
+    async tableExists(names) {
+        this.#requireStarted();
+        if (!names.length)
+            return [];
+        const { dialect } = this.config;
+        let present;
+        if (dialect === 'sqlite') {
+            const rows = await this.query(`SELECT name FROM sqlite_master WHERE type = 'table' AND name IN (${names.map(() => '?').join(', ')})`, [...names]);
+            present = rows.map(row => row.name);
+        }
+        else if (dialect === 'pg') {
+            present = [];
+            for (const name of names) {
+                const [row] = await this.query('SELECT to_regclass($1) IS NOT NULL AS present', [quoteTableName('pg', name)]);
+                if (row?.present === true)
+                    present.push(name);
+            }
+        }
+        else if (dialect === 'mysql') {
+            const rows = await this.query(`SELECT TABLE_NAME AS name FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME IN (${names.map(() => '?').join(', ')})`, [...names]);
+            present = rows.map(row => String(row.name ?? row.TABLE_NAME));
+        }
+        else if (dialect === 'mongodb') {
+            const rows = await this.#db.query({ collection: names[0], operation: 'listCollections', filter: { name: { $in: [...names] } } });
+            present = rows.map(row => row.name);
+        }
+        else {
+            return [];
+        }
+        return names.filter(name => present.includes(name));
+    }
+    /**
+     * 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.
+     */
+    async readSnapshot(tables) {
+        this.#requireStarted();
+        const { dialect } = this.config;
+        const out = {};
+        if (dialect === 'mongodb') {
+            for (const table of tables) {
+                const rows = [];
+                let after;
+                for (;;) {
+                    const batch = await this.#db.query({
+                        collection: table,
+                        operation: 'find',
+                        filter: after === undefined ? {} : { id: { $gt: after } },
+                        sort: { id: 1 },
+                        limit: SNAPSHOT_BATCH_SIZE,
+                    });
+                    for (const document of batch) {
+                        const { _id: _ignored, ...row } = document;
+                        rows.push(row);
+                    }
+                    if (batch.length < SNAPSHOT_BATCH_SIZE)
+                        break;
+                    after = batch[batch.length - 1].id;
+                }
+                out[table] = rows;
+            }
+            return Object.freeze(out);
+        }
+        this.#requireSql();
+        await this.transaction(async (trx) => {
+            for (const table of tables) {
+                const rows = [];
+                let after;
+                for (;;) {
+                    const where = after === undefined ? '' : ` WHERE id > ${placeholder(dialect, 1)}`;
+                    const batch = await trx.query(`SELECT * FROM ${quoteTableName(dialect, table)}${where} ORDER BY id LIMIT ${SNAPSHOT_BATCH_SIZE}`, after === undefined ? [] : [after]);
+                    rows.push(...batch.map(row => ({ ...row })));
+                    if (batch.length < SNAPSHOT_BATCH_SIZE)
+                        break;
+                    after = batch[batch.length - 1].id;
+                }
+                out[table] = rows;
+            }
+        }, { readOnly: true, repeatableRead: dialect !== 'sqlite' });
+        return Object.freeze(out);
+    }
+    /**
+     * 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.
+     */
+    async dropTables(tables) {
+        this.#requireStarted();
+        const { dialect } = this.config;
+        if (dialect === 'mongodb') {
+            for (const table of await this.tableExists(tables)) {
+                await this.#db.query({ collection: table, operation: 'dropCollection', filter: {} });
+            }
+            return;
+        }
+        this.#requireSql();
+        const statements = tables.map(table => `DROP TABLE IF EXISTS ${quoteTableName(dialect, table)}`);
+        if (dialect === 'mysql') {
+            for (const statement of statements)
+                await this.query(statement);
+            return;
+        }
+        await this.transaction(async (trx) => {
+            for (const statement of statements)
+                await trx.query(statement);
+        });
+    }
+    /** The gateway's marker (ADR 0059 §3 修订): which gateway.db holds the Console accounts, or undefined. */
+    async readStoreMarker() {
+        this.#requireStarted();
+        const { dialect } = this.config;
+        if (!(await this.tableExists([GATEWAY_STORE_MARKER_TABLE])).length)
+            return undefined;
+        if (dialect === 'mongodb') {
+            const [row] = await this.#db.query({ collection: GATEWAY_STORE_MARKER_TABLE, operation: 'find', filter: { id: 'gateway' }, limit: 1 });
+            return row ? markerOf(row) : undefined;
+        }
+        const [row] = await this.query(`SELECT store_id, migrated_at FROM ${quoteTableName(dialect, GATEWAY_STORE_MARKER_TABLE)} WHERE id = ${placeholder(dialect, 1)}`, ['gateway']);
+        return row ? markerOf(row) : undefined;
+    }
+    /** Writes (replaces) the marker. */
+    async writeStoreMarker(marker) {
+        this.#requireStarted();
+        const { dialect } = this.config;
+        if (dialect === 'mongodb') {
+            await this.#db.query({ collection: GATEWAY_STORE_MARKER_TABLE, operation: 'deleteMany', filter: { id: 'gateway' } });
+            await this.#db.query({ collection: GATEWAY_STORE_MARKER_TABLE, operation: 'insertOne', filter: {} }, [{ id: 'gateway', store_id: marker.storeId, migrated_at: marker.migratedAt }]);
+            return;
+        }
+        this.#requireSql();
+        const table = quoteTableName(dialect, GATEWAY_STORE_MARKER_TABLE);
+        await this.query(`CREATE TABLE IF NOT EXISTS ${table} (id VARCHAR(32) NOT NULL PRIMARY KEY, store_id VARCHAR(64) NOT NULL, migrated_at BIGINT NOT NULL)`);
+        if (dialect === 'pg') {
+            // The main account's default privileges would grant it to the restricted Console account
+            // (ADR 0059 §4): take that, and PUBLIC's, away at once. (MySQL grants that account the whole
+            // database; there only the text guard and the start-up probe keep it off this table.)
+            await this.query(`REVOKE ALL ON TABLE ${table} FROM PUBLIC`);
+            // Every role the default privileges (or anyone) granted it to, the console account included,
+            // whether or not this connection knows `database.console`.
+            const grantees = await this.query(`SELECT DISTINCT a.grantee::regrole::text AS grantee
+        FROM pg_class c, aclexplode(c.relacl) a WHERE c.oid = to_regclass($1) AND a.grantee <> c.relowner AND a.grantee <> 0`, [table]);
+            for (const { grantee } of grantees)
+                await this.query(`REVOKE ALL ON TABLE ${table} FROM ${grantee}`);
+        }
+        await this.transaction(async (trx) => {
+            await trx.query(`DELETE FROM ${table} WHERE id = ${placeholder(dialect, 1)}`, ['gateway']);
+            await trx.query(`INSERT INTO ${table} (id, store_id, migrated_at) VALUES (${placeholder(dialect, 1)}, ${placeholder(dialect, 2)}, ${placeholder(dialect, 3)})`, ['gateway', marker.storeId, marker.migratedAt]);
+        });
+    }
+    /** Removes the marker (revert to a version without it). */
+    async deleteStoreMarker() {
+        await this.dropTables([GATEWAY_STORE_MARKER_TABLE]);
+    }
     async start() {
         if (this.#started)
             return;

package/lib/http/gateway-console.d.ts

@@ -1,7 +1,7 @@
 import { type ConsoleAuditEntry } from '@zhin.js/host-http';
 import { type ConsolePluginPermissionInfo } from '@zhin.js/console-protocol';
 import { type ProjectDatabaseConfig } from '../database/config.js';
-import { ProjectDatabase } from '../database/project-database.js';
+import { type GatewayStore, type OpenGatewayStoreOptions } from '../database/gateway-store.js';
 import { type LocalConsoleAdmin } from '../iam/local-admin.js';
 import { ConsoleIamService } from '../iam/service.js';
 import { ConsoleSetupService } from '../iam/setup-service.js';
@@ -26,26 +26,33 @@ export interface GatewayConsoleOptions {
     readonly instance?: GatewayConsoleInstancePort;
     /** Restarts the instance after the setup wizard switched databases (ADR 0054 §7). */
     readonly restartInstance?: () => Promise<void>;
-    /** Overrides the project `database` block (tests). */
+    /** Overrides the project `database` block the old `console_*` tables are imported from (tests). */
     readonly database?: ProjectDatabaseConfig;
+    /** Gateway store overrides (tests; default `.zhin/gateway.db`). */
+    readonly store?: OpenGatewayStoreOptions;
     /** Overrides the project `console.terminal` block. */
     readonly terminal?: unknown;
     readonly onboarding?: OnboardingService;
-    /** Retry interval while the database cannot be opened. Default 10 s. */
+    /** Retry interval while gateway.db or the import of the old tables fails. Default 10 s. */
     readonly retryMs?: number;
 }
 export interface GatewayConsole {
-    /** Settles once the first database open attempt finished (never rejects). */
+    /** Settles once the first open attempt finished (never rejects). */
     readonly ready: Promise<void>;
-    /** The IAM service bound to the open database; undefined when the dialect cannot hold accounts. */
+    /** The IAM service; fails closed (`unavailableReason()`) until gateway.db is open and imported. */
     iam(): ConsoleIamService | undefined;
-    /** The gateway's database connection (undefined before the first open). */
-    database(): ProjectDatabase | undefined;
+    /** The gateway store `.zhin/gateway.db` (undefined before it opened). */
+    database(): GatewayStore | undefined;
     readonly setup: ConsoleSetupService;
     readonly onboarding: OnboardingService;
     readonly terminal: ConsoleTerminalHandle;
-    /** Closes the gateway's connection and opens the configured database again (setup wizard). */
+    /** Closes gateway.db and opens it again (and retries a pending import). */
     reopenDatabase(): Promise<void>;
+    /**
+     * Writes the store marker into the project database if it is missing (after the first owner was
+     * created and after the instance first reported ready: a first-run project file exists by then).
+     */
+    ensureStoreMarker(): Promise<void>;
     /** Socket-only `gateway.console.*` (`zhin console init` / `zhin console user` beside the gateway). */
     readonly localAdmin: LocalConsoleAdmin;
     close(): Promise<void>;

package/lib/http/gateway-console.js

@@ -1,8 +1,10 @@
 /**
- * Console access control in the gateway (ADR 0054 §3 / §7, ADR 0049, ADR 0053 §4): the gateway
- * opens the project database itself, owns the `console_*` tables, authenticates sessions / API
- * tokens / the bootstrap token locally, and serves `/auth/*`, `iam.*`, `onboarding.update`, the
- * setup wizard, the terminal and the audit log — all without an instance.
+ * Console access control in the gateway (ADR 0054 §3 / §7, ADR 0049, ADR 0053 §4, ADR 0059): the
+ * gateway keeps the access-control tables in its own store `.zhin/gateway.db`, authenticates
+ * sessions / API tokens / the bootstrap token locally, and serves `/auth/*`, `iam.*`,
+ * `onboarding.update`, the setup wizard, the terminal and the audit log — all without an
+ * instance. It holds no connection to the project database: it connects only to import the
+ * tables an earlier version left there (and the setup wizard tests a connection).
  *
  * The instance contributes what only it knows over the bridge: the plugin permission catalog
  * (`catalog`) and its own audit entries (`audit`); the gateway tells it when a user's credentials
@@ -17,27 +19,39 @@ import { formatCompact, getLogger } from '@zhin.js/logger';
 import { ConsoleConfigurationStore } from '../config/configuration.js';
 import { readEnvFile, writeEnvFile } from '../config/environment-files.js';
 import { loadExpandedProjectConfig, resolveProjectDatabaseConfig } from '../database/config.js';
-import { ProjectDatabase } from '../database/project-database.js';
+import { openGatewayStore } from '../database/gateway-store.js';
 import { projectEnvironment } from '../iam/install.js';
 import { createLocalConsoleAdmin } from '../iam/local-admin.js';
 import { registerConsoleAuthRoutes } from '../iam/routes.js';
 import { dispatchIamRpc, isIamRpc } from '../iam/rpc.js';
+import { ensureGatewayStoreMarker, importLegacyIamTables, inspectLegacyIamImport, isTransientLegacyImportError, LegacyImportError, readLegacyImportRecord } from '../iam/legacy-import.js';
 import { ConsoleIamService } from '../iam/service.js';
 import { ConsoleSetupService } from '../iam/setup-service.js';
-import { defineConsoleIamTables } from '../iam/tables.js';
 import { OnboardingError } from '../onboarding/errors.js';
 import { OnboardingService } from '../onboarding/service.js';
 import { findConfigFile } from '../project/config-file.js';
 import { installHostConsoleTerminal } from '../terminal/host.js';
 const logger = getLogger('gateway');
 const DEFAULT_RETRY_MS = 10_000;
-/** A database that never starts: the IAM service then fails closed on its setup marker. */
+/** Cap of the retry backoff while the project database stays unreachable. */
+const MAX_RETRY_MS = 5 * 60_000;
+/** A database that never starts: the IAM service then fails closed. */
 const UNAVAILABLE_DATABASE = Object.freeze({ started: false, models: Object.freeze({ get: () => undefined }) });
 export async function startGatewayConsole(options) {
     const { server, projectRoot } = options;
+    /** Why access control is closed (undefined once gateway.db is open and the import settled). */
+    let pending = 'Console 访问控制正在启动';
+    /** Category of `pending` shown to anonymous callers (never the detail). */
+    let pendingCode = 'starting';
+    /** Consecutive transient failures (backoff exponent). */
+    let failures = 0;
     const failClosed = () => ({
-        service: new ConsoleIamService({ database: UNAVAILABLE_DATABASE, projectRoot }),
-        supported: true,
+        service: new ConsoleIamService({
+            database: UNAVAILABLE_DATABASE,
+            projectRoot,
+            unavailable: () => pending ?? 'Console 访问控制正在重新连接',
+            unavailableCode: () => (pending === undefined ? 'starting' : pendingCode),
+        }),
         dispose: [],
     });
     const environment = options.environment ?? 'development';
@@ -52,12 +66,12 @@ export async function startGatewayConsole(options) {
     let closed = false;
     let retryTimer;
     let opening;
-    const iam = () => (connection.supported ? connection.service : undefined);
+    const iam = () => connection.service;
     const disposers = [];
     // Level grants need the catalog of the instance's loaded plugins (kept across restarts).
     disposers.push(registry.usePluginPermissions(() => options.instance?.pluginPermissions?.() ?? []));
     const access = Object.freeze({
-        initialized: () => connection.service?.initialized() ?? false,
+        initialized: () => connection.service.initialized(),
         authenticate: async (token, meta) => (await iam()?.authenticate(token, meta)) ?? null,
         audit: (entry) => { iam()?.audit(entry); },
     });
@@ -79,68 +93,134 @@ export async function startGatewayConsole(options) {
         }
         catch { /* bridge gone */ }
     };
+    const projectDatabase = async () => options.database
+        ?? resolveProjectDatabaseConfig(projectRoot, await loadExpandedProjectConfig(projectRoot, environment));
     async function connect() {
-        let config;
+        let store;
         try {
-            config = options.database ?? await resolveProjectDatabaseConfig(projectRoot, await loadExpandedProjectConfig(projectRoot, environment));
+            store = await openGatewayStore(projectRoot, options.store ?? {});
         }
         catch (error) {
-            logger.warn(formatCompact({ op: 'gateway_database_config_invalid', error: errorText(error) }));
-            connection = failClosed();
+            pending = `无法打开 .zhin/gateway.db：${errorText(error)}`;
+            pendingCode = 'store';
+            logger.warn(formatCompact({ op: 'gateway_store_open_failed', error: errorText(error) }));
+            scheduleRetry();
             return;
         }
-        let database;
+        connection = { database: store, service: connection.service, dispose: [] };
+        // ADR 0059 §3: the old console_* tables of the project database come over before anything
+        // reads gateway.db; until then access control stays closed (an empty store is not "no owner").
         try {
-            database = new ProjectDatabase(config);
+            const record = await importLegacyIamTables({
+                store,
+                projectRoot,
+                projectDatabase,
+                logger: { info: (message) => logger.info(message), warn: (message) => logger.warn(message) },
+            });
+            if (record.status === 'done' && record.changed) {
+                logger.warn(formatCompact({ op: 'gateway_legacy_import_changed', export: record.changedExport }));
+            }
         }
         catch (error) {
-            logger.warn(formatCompact({ op: 'gateway_database_driver_failed', dialect: config.dialect, error: errorText(error) }));
-            connection = failClosed();
-            return;
-        }
-        const supported = defineConsoleIamTables(database);
-        if (!supported) {
-            logger.warn('console iam: the configured database cannot store Console users; run the setup wizard to choose sqlite/mysql/pg/mongodb');
-            connection = { database, supported: false, dispose: [] };
+            const code = error instanceof LegacyImportError ? error.code : 'error';
+            const transient = isTransientLegacyImportError(error);
+            pending = code === 'store_lost' || code === 'store_mismatch'
+                ? errorText(error)
+                : transient
+                    ? `正在等待项目数据库，以迁移旧版的 Console 账号表：${errorText(error)}`
+                    : `迁移旧版 Console 账号表失败，需要处理后重启网关（zhin stop && zhin start）：${errorText(error)}`;
+            pendingCode = code === 'store_lost' || code === 'store_mismatch' ? code : transient ? 'migration_pending' : 'migration_failed';
+            logger.warn(formatCompact({ op: 'gateway_legacy_import_failed', code, transient, error: errorText(error) }));
+            // Retrying cannot fix a conflict, a mismatch or a lost store: stay closed until the operator acts.
+            if (transient)
+                scheduleRetry();
             return;
         }
         const service = new ConsoleIamService({
-            database,
+            database: store,
             projectRoot,
             onError: (error) => logger.warn(`console iam: ${errorText(error)}`),
             pluginPermissions: () => registry.pluginPermissions(),
+            onOwnerCreated: () => { void ensureStoreMarker(); },
         });
-        const dispose = [service.onCredentialsRevoked(({ userId, reason }) => revoke(userId, reason))];
-        connection = { database, service, supported: true, dispose };
         try {
-            await database.start();
             await service.start();
-            logger.info(formatCompact({ op: 'gateway_database_open', dialect: config.dialect }));
         }
         catch (error) {
-            // Not ready: `/auth/*` answers 503 and the owner state comes from the setup marker.
-            logger.warn(formatCompact({ op: 'gateway_database_open_failed', dialect: config.dialect, error: errorText(error) }));
+            pending = `Console 访问控制无法启动：${errorText(error)}`;
+            pendingCode = 'store';
+            logger.warn(formatCompact({ op: 'gateway_store_open_failed', error: errorText(error) }));
+            service.stop();
             scheduleRetry();
+            return;
         }
+        const dispose = [service.onCredentialsRevoked(({ userId, reason }) => revoke(userId, reason))];
+        connection = { database: store, service, dispose };
+        pending = undefined;
+        failures = 0;
+        logger.info(formatCompact({ op: 'gateway_store_open', file: store.filename }));
     }
+    /** Writes the project database's store marker if missing; a foreign marker closes the Console. */
+    async function ensureStoreMarker() {
+        const store = connection.database;
+        if (!store || pending !== undefined)
+            return;
+        try {
+            await ensureGatewayStoreMarker({ store, projectRoot, projectDatabase, logger: { warn: (message) => logger.warn(message) } });
+        }
+        catch (error) {
+            if (error instanceof LegacyImportError && (error.code === 'store_mismatch' || error.code === 'store_lost')) {
+                // The project database belongs to another gateway.db (found after the start, e.g. once the
+                // project database became reachable): the same fail-closed state as at connect — Console
+                // closed, no retry, until the operator acts (`zhin console init --reset-store`).
+                logger.warn(formatCompact({ op: 'gateway_legacy_import_failed', code: error.code, transient: false, error: errorText(error) }));
+                opening = (opening ?? Promise.resolve()).then(async () => {
+                    const current = connection;
+                    if (closed || current.database !== store)
+                        return;
+                    pending = errorText(error);
+                    pendingCode = error.code;
+                    const users = await current.service.listUsers().catch(() => []);
+                    // gateway.db stays open (the local owner can inspect it, `--reset-store` can run).
+                    connection = { database: store, service: failClosed().service, dispose: [] };
+                    for (const dispose of current.dispose.splice(0))
+                        dispose();
+                    current.service.stop();
+                    // Sessions and API tokens no longer authenticate (the service is closed); what is already
+                    // open ends too: terminals and the instance's sockets of every user, as on a revocation.
+                    for (const user of users)
+                        revoke(user.id, error.code);
+                    for (const session of terminal.sessions())
+                        terminal.terminatePrincipal(session.principalId, 'revoked');
+                });
+                await opening;
+                return;
+            }
+            logger.warn(formatCompact({ op: 'gateway_store_marker_failed', error: errorText(error) }));
+        }
+    }
+    /** Transient failure: retry with a growing delay (retryMs, 2×, 4×, … at most MAX_RETRY_MS). */
     function scheduleRetry() {
         if (closed || retryTimer)
             return;
+        const delay = Math.min(retryMs * 2 ** failures, Math.max(retryMs, MAX_RETRY_MS));
+        failures += 1;
         retryTimer = setTimeout(() => {
             retryTimer = undefined;
             if (closed)
                 return;
             void reopen();
-        }, retryMs);
+        }, delay);
         retryTimer.unref?.();
     }
     async function disconnect() {
         const current = connection;
+        pending ??= 'Console 访问控制正在重新连接';
         connection = failClosed();
         for (const dispose of current.dispose.splice(0))
             dispose();
-        current.service?.stop();
-        await current.database?.stop().catch((error) => {
+        current.service.stop();
+        await current.database?.close().catch((error) => {
             logger.warn(formatCompact({ op: 'gateway_database_close_failed', error: errorText(error) }));
         });
     }
@@ -169,7 +249,7 @@ export async function startGatewayConsole(options) {
     });
     const onboarding = options.onboarding ?? new OnboardingService({
         projectRoot,
-        hasOwner: () => connection.service?.initialized() ?? false,
+        hasOwner: () => connection.service.initialized(),
     });
     const restartInstance = () => {
         void options.restartInstance?.().catch((error) => {
@@ -179,12 +259,18 @@ export async function startGatewayConsole(options) {
     const localAdmin = createLocalConsoleAdmin({
         setup,
         iam,
-        // ADR 0054 §7, as for the web wizard: the gateway uses the new database before it answers.
+        // The accounts stay in gateway.db (ADR 0059): only the instance uses the new database.
         switchDatabase: async () => {
-            await reopen();
             restartInstance();
             return { restarting: options.restartInstance !== undefined };
         },
+        migration: async () => {
+            const store = connection.database;
+            if (!store)
+                return { pending };
+            const inspection = await inspectLegacyIamImport({ store, projectRoot, projectDatabase });
+            return { ...inspection, record: inspection.record ?? await readLegacyImportRecord(store), ...(pending !== undefined ? { pending, pendingCode } : {}) };
+        },
     });
     disposers.push(...registerConsoleAuthRoutes({
         http: server,
@@ -192,18 +278,14 @@ export async function startGatewayConsole(options) {
         iam,
         setup,
         onboarding: () => onboarding.status(),
-        // ADR 0054 §7: close the gateway's connection, open the new database, restart the instance.
-        requestRestart: () => {
-            void reopen()
-                .then(() => options.restartInstance?.())
-                .catch((error) => logger.warn(formatCompact({ op: 'gateway_database_switch_failed', error: errorText(error) })));
-        },
+        // The instance restarts on the new project database; the accounts stay in gateway.db (ADR 0059).
+        requestRestart: () => { restartInstance(); },
     }));
     // `/auth/*` belongs to the gateway alone: nothing under it is forwarded to the instance.
     disposers.push(server.route('ALL', `${server.apiBase}/auth/*`, () => jsonResponse(404, { success: false, code: 'not_found', error: 'Not found' }), { summary: 'Unknown /auth route', tags: ['auth'] }));
     disposers.push(server.useConsoleRpc(createGatewayAccountRpc({ iam, onboarding })));
     const ready = reopen().catch((error) => {
-        logger.warn(formatCompact({ op: 'gateway_database_open_failed', error: errorText(error) }));
+        logger.warn(formatCompact({ op: 'gateway_store_open_failed', error: errorText(error) }));
     });
     let closeResult;
     return Object.freeze({
@@ -214,6 +296,7 @@ export async function startGatewayConsole(options) {
         onboarding,
         terminal,
         reopenDatabase: reopen,
+        ensureStoreMarker,
         localAdmin,
         close() {
             closeResult ??= (async () => {

package/lib/http/plugin-switch-rpc.js

@@ -197,7 +197,11 @@ function disabledPlugins(document) {
     const list = document?.disable_plugins;
     return Object.freeze(Array.isArray(list) ? list.filter((item) => typeof item === 'string') : []);
 }
-/** The global plugin switch's warnings about the plugin's own overrides (as the instance computed them). */
+/**
+ * The global plugin switch's warnings about a legacy `overrides` block still in the file (as the
+ * instance computed them). Since ADR 0057 §2 adapter / account overrides live in the instance's
+ * database, which the gateway does not read, so this only reports a block waiting for its import.
+ */
 function overrideWarnings(document, plugin) {
     const block = document[plugin];
     const overrides = block && typeof block === 'object' && !Array.isArray(block) ? block[FEATURE_OVERRIDES_KEY] : undefined;

package/lib/http/start-gateway.js

@@ -141,6 +141,15 @@ export async function startGateway(options) {
                 },
             });
             await settleWithin(gatewayConsole.ready, options.databaseWaitMs ?? 10_000);
+            // ADR 0059 §3: once the instance runs, a first-run SQLite project file exists; make sure the
+            // store marker is there (normally written at connect time already).
+            let markerChecked = false;
+            supervisor.on('state', (status) => {
+                if (markerChecked || status.state !== 'running')
+                    return;
+                markerChecked = true;
+                void gatewayConsole?.ensureStoreMarker();
+            });
         }
         assertNotOpenOnNetwork(http, server.tokenRegistry);
         // Settings for the first instance start, read before listening so it starts right away.

package/lib/iam/index.d.ts

@@ -1,7 +1,8 @@
 export { installConsoleIam, projectEnvironment, type ConsoleIamInstallation, type InstallConsoleIamOptions } from './install.js';
-export { accountInputProblem, ConsoleIamService, IamError, type BindingInput, type ConsoleAuditView, type ConsoleBindingView, type ConsoleCredentialRevocation, type ConsoleCredentialRevocationReason, type ConsoleIamServiceOptions, type ConsoleRoleView, type ConsoleTokenView, type ConsoleUserView, type IamDatabase, type IamErrorCode, } from './service.js';
-export { ConsoleSetupService, SETUP_NO_MIGRATION_NOTICE, upsertDotenv, type ConsoleSetupServiceOptions, type SetupConfigPort, type SetupDatabaseField, type SetupDatabaseInput, type SetupDatabaseSummary, type SetupDriver, type SetupEnvFilePort, type SetupStatus, } from './setup-service.js';
-export { defineConsoleIamTables, IAM_DIALECTS, IAM_TABLE_DEFINITIONS, IAM_TABLES } from './tables.js';
+export { accountInputProblem, IAM_UNAVAILABLE_PUBLIC_MESSAGE, ConsoleIamService, IamError, type BindingInput, type ConsoleAuditView, type ConsoleBindingView, type ConsoleCredentialRevocation, type ConsoleCredentialRevocationReason, type ConsoleIamServiceOptions, type ConsoleRoleView, type ConsoleTokenView, type ConsoleUserView, type IamDatabase, type IamErrorCode, } from './service.js';
+export { ConsoleSetupService, SETUP_CONSOLE_ROLE_NOTICE, SETUP_NO_MIGRATION_NOTICE, upsertDotenv, type ConsoleSetupServiceOptions, type SetupConfigPort, type SetupDatabaseField, type SetupDatabaseInput, type SetupDatabaseSummary, type SetupDriver, type SetupEnvFilePort, type SetupStatus, } from './setup-service.js';
+export { defineConsoleIamTables, IAM_TABLE_DEFINITIONS, IAM_TABLES, type IamTableHost } from './tables.js';
+export { importLegacyIamTables, ensureGatewayStoreMarker, isTransientLegacyImportError, LEGACY_IMPORT_FAILURE_KEY, resetGatewayStore, type LegacyImportFailure, inspectLegacyIamImport, LEGACY_IMPORT_KEY, LegacyImportError, legacyImportSettled, readLegacyImportRecord, revertLegacyIamImport, tableChecksum, type LegacyIamSource, type LegacyImportErrorCode, type LegacyImportInspection, type LegacyImportOptions, type LegacyImportRecord, type LegacySourceSummary, type RevertLegacyImportResult, } from './legacy-import.js';
 export { dispatchIamRpc, isIamRpc } from './rpc.js';
 export { registerConsoleAuthRoutes } from './routes.js';
 export { LoginRateLimiter } from './rate-limit.js';

package/lib/iam/index.js

@@ -1,7 +1,8 @@
 export { installConsoleIam, projectEnvironment } from './install.js';
-export { accountInputProblem, ConsoleIamService, IamError, } from './service.js';
-export { ConsoleSetupService, SETUP_NO_MIGRATION_NOTICE, upsertDotenv, } from './setup-service.js';
-export { defineConsoleIamTables, IAM_DIALECTS, IAM_TABLE_DEFINITIONS, IAM_TABLES } from './tables.js';
+export { accountInputProblem, IAM_UNAVAILABLE_PUBLIC_MESSAGE, ConsoleIamService, IamError, } from './service.js';
+export { ConsoleSetupService, SETUP_CONSOLE_ROLE_NOTICE, SETUP_NO_MIGRATION_NOTICE, upsertDotenv, } from './setup-service.js';
+export { defineConsoleIamTables, IAM_TABLE_DEFINITIONS, IAM_TABLES } from './tables.js';
+export { importLegacyIamTables, ensureGatewayStoreMarker, isTransientLegacyImportError, LEGACY_IMPORT_FAILURE_KEY, resetGatewayStore, inspectLegacyIamImport, LEGACY_IMPORT_KEY, LegacyImportError, legacyImportSettled, readLegacyImportRecord, revertLegacyIamImport, tableChecksum, } from './legacy-import.js';
 export { dispatchIamRpc, isIamRpc } from './rpc.js';
 export { registerConsoleAuthRoutes } from './routes.js';
 export { LoginRateLimiter } from './rate-limit.js';