@zhin.js/gateway 1.1.1 → 1.2.0

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>;
 }

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/console-rpc.d.ts

@@ -12,8 +12,16 @@ export declare const GATEWAY_RPC_PREFIX = "gateway.";
 export interface GatewayConsoleRpc {
     handle(message: Readonly<Record<string, unknown>>, context: RouteContext, tokenRegistry: TokenRegistry): Promise<Response>;
 }
-/** Further gateway-owned RPC types (`iam.*`, `onboarding.update`), see `GatewayHttpServer.useConsoleRpc`. */
+/**
+ * Further gateway-owned RPC types (`iam.*`, `onboarding.update`, the global plugin switch), see
+ * `GatewayHttpServer.useConsoleRpc`.
+ */
 export interface GatewayRpcHandler extends GatewayConsoleRpc {
     owns(type: string): boolean;
+    /**
+     * Narrows {@link owns} by payload: when present and false for the parsed message, the request
+     * is forwarded to the instance untouched (e.g. `feature.set-enabled` below the global level).
+     */
+    claims?(message: Readonly<Record<string, unknown>>): boolean;
 }
 export declare function createGatewayConsoleRpc(dispatch: GatewayRpcDispatcher): GatewayConsoleRpc;

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>;