@hozon/db 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Le Cam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,18 @@
-# Temporary Holding Version
+# @hozon/db
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Database lifecycle, store registration, migrations, transactions, and savepoints.
+
+```sh
+pnpm add @hozon/db @hozon/node-sqlite
+```
+
+```ts
+import { HozonDB } from '@hozon/db'
+import { NodeSQLiteAdapter } from '@hozon/node-sqlite'
+
+const db = new HozonDB({ adapter: new NodeSQLiteAdapter({ database: 'app.sqlite' }) })
+await db.migrate()
+await db.close()
+```
+
+See the [database reference](../../docs/reference/db.md).

package/lib/db.d.ts

@@ -0,0 +1,79 @@
+import type { Adapter, ColumnTypes, Functions } from '@hozon/adapter';
+import { type Logger } from '@sozai/log';
+import { Kysely } from 'kysely';
+import { type Migration } from 'kysely/migration';
+export type MigrationContext = {
+    tablePrefix: string;
+    kind: Adapter['kind'];
+    types: ColumnTypes;
+    functions: Functions;
+};
+export type StoreDefinition<Tables, API> = {
+    name: string;
+    migrations: Record<string, Migration> | ((ctx: MigrationContext) => Record<string, Migration>);
+    dependsOn?: Array<string>;
+    createAPI: (db: Kysely<Tables>, adapter: Adapter) => API;
+};
+export type StoreProvider<Stores extends Record<string, unknown> = Record<string, unknown>> = {
+    getStore<S extends keyof Stores & string>(name: S): Promise<Stores[S]>;
+    /**
+     * Returns whether a store definition is registered, synchronously and
+     * WITHOUT triggering migration. This distinguishes "plugin not installed"
+     * (registration absent) from "plugin installed but its store currently
+     * errors" — callers can fail closed on the latter instead of mistaking a
+     * transient store error for an uninstalled plugin.
+     */
+    hasStore(name: string): boolean;
+    onCommit(fn: () => void): void;
+    /**
+     * Register a hook to run after the transaction rolls back. By the time the
+     * hook fires the DB is already reverted, so it is the correct place to drop
+     * any in-memory state that was eagerly advanced in anticipation of a commit
+     * (e.g. cache invalidation). Like `onCommit`, hooks are isolated and their
+     * errors logged, never re-thrown. On the non-transactional provider it is a
+     * no-op (each standalone op auto-commits; nothing to roll back).
+     */
+    onRollback(fn: () => void): void;
+    /**
+     * Run `fn` against a `StoreProvider` that scopes its writes to a transaction.
+     *
+     * On `HozonDB`, opens a fresh DB transaction and provides a transactional
+     * `tx` provider; the outer provider's `onCommit` hooks fire after commit.
+     *
+     * On a transactional `tx` provider obtained from a parent
+     * `withTransaction` call, this method runs `fn` inline with `this` as the
+     * nested `tx`. The underlying driver does not nest transactions
+     * (no implicit savepoints), so atomicity is inherited from the enclosing
+     * transaction or explicit savepoint.
+     */
+    withTransaction<NestedStores extends Record<string, unknown>, R>(fn: (tx: StoreProvider<NestedStores>) => Promise<R>): Promise<R>;
+    /** Roll back only this unit of work when called inside a transaction. */
+    withSavepoint?<NestedStores extends Record<string, unknown>, R>(fn: (tx: StoreProvider<NestedStores>) => Promise<R>): Promise<R>;
+};
+export type HozonDBParams = {
+    adapter: Adapter;
+    logger?: Logger;
+    tablePrefix?: string;
+};
+export declare class HozonDB implements StoreProvider {
+    #private;
+    constructor(params: HozonDBParams);
+    get adapter(): Adapter;
+    register<Tables, API>(store: StoreDefinition<Tables, API>): void;
+    getStore<T>(name: string): Promise<T>;
+    hasStore(name: string): boolean;
+    onCommit(fn: () => void): void;
+    onRollback(_fn: () => void): void;
+    /**
+     * Runs `fn` inside a DB transaction and provides a scoped `StoreProvider`.
+     * Concurrent calls on the same `HozonDB` instance are supported — the
+     * underlying driver serializes them.
+     *
+     * Callers MUST use the provided `tx` inside the callback. Calling
+     * `db.withTransaction` on the same instance inside the callback opens a
+     * new independent transaction (no atomic nesting) and is a bug.
+     */
+    withTransaction<Stores extends Record<string, unknown>, R>(fn: (tx: StoreProvider<Stores>) => Promise<R>): Promise<R>;
+    migrate(): Promise<void>;
+    close(): Promise<void>;
+}

package/lib/db.js

@@ -0,0 +1,301 @@
+import { getLogger } from '@sozai/log';
+import { Kysely, ParseJSONResultsPlugin, sql } from 'kysely';
+import { Migrator } from 'kysely/migration';
+import { withTransactionalDDL } from './dialect.js';
+import { HozonDBClosedError, InvalidTablePrefixError, SavepointOverlapError } from './errors.js';
+import { checkStore } from './preflight.js';
+import { TablePrefixPlugin } from './table-prefix.js';
+export class HozonDB {
+    #tablePrefix;
+    #closed = false;
+    #closing = null;
+    #preflight = null;
+    #checked = new Set();
+    #migrations = new Map();
+    #adapter;
+    #db;
+    #storeDB;
+    #logger;
+    #migrated = new Map();
+    #storeAPIs = new Map();
+    #stores = new Map();
+    constructor(params){
+        this.#tablePrefix = params.tablePrefix ?? 'hozon';
+        if (!/^[a-z][a-z0-9_]{0,30}$/.test(this.#tablePrefix)) {
+            throw new InvalidTablePrefixError(this.#tablePrefix);
+        }
+        this.#adapter = params.adapter;
+        this.#db = new Kysely({
+            // SQLite supports transactional DDL, but Kysely's SQLite adapters do not report it.
+            dialect: this.#adapter.kind === 'sqlite' ? withTransactionalDDL(this.#adapter.dialect) : this.#adapter.dialect,
+            plugins: [
+                new ParseJSONResultsPlugin()
+            ]
+        });
+        this.#storeDB = this.#db.withPlugin(new TablePrefixPlugin(this.#tablePrefix));
+        this.#logger = params.logger ?? getLogger([
+            'hozon',
+            'db'
+        ]);
+    }
+    get adapter() {
+        return this.#adapter;
+    }
+    register(store) {
+        const existing = this.#stores.get(store.name);
+        if (existing != null) {
+            if (existing !== store) {
+                this.#logger.warn('store "{name}" registered with different definition, ignoring', {
+                    name: store.name
+                });
+            }
+            return;
+        }
+        this.#stores.set(store.name, store);
+    }
+    async getStore(name) {
+        this.#assertOpen();
+        await this.#ensurePreflight();
+        await this.#ensureMigrated(name);
+        this.#assertOpen();
+        if (!this.#storeAPIs.has(name)) {
+            const store = this.#stores.get(name);
+            if (store == null) {
+                throw new Error(`Store "${name}" is not registered`);
+            }
+            this.#storeAPIs.set(name, store.createAPI(this.#storeDB, this.#adapter));
+        }
+        return this.#storeAPIs.get(name);
+    }
+    hasStore(name) {
+        return this.#stores.has(name);
+    }
+    onCommit(fn) {
+        fn();
+    }
+    // Each standalone op auto-commits, so there is nothing to roll back — no-op.
+    onRollback(_fn) {}
+    /**
+   * Runs `fn` inside a DB transaction and provides a scoped `StoreProvider`.
+   * Concurrent calls on the same `HozonDB` instance are supported — the
+   * underlying driver serializes them.
+   *
+   * Callers MUST use the provided `tx` inside the callback. Calling
+   * `db.withTransaction` on the same instance inside the callback opens a
+   * new independent transaction (no atomic nesting) and is a bug.
+   */ async withTransaction(fn) {
+        // Migrate every registered store before opening the transaction. Stores
+        // are internal and known up front, so a broken migration should fail fast
+        // at startup rather than leave a runtime partition where one store's
+        // failure silently blocks transactions that never touch it.
+        await this.migrate();
+        this.#assertOpen();
+        const commitHooks = [];
+        const rollbackHooks = [];
+        let result;
+        let savepointID = 0;
+        try {
+            result = await this.#storeDB.transaction().execute(async (trx)=>{
+                const txKysely = trx;
+                const txStoreAPIs = new Map();
+                const createScopedProvider = (scopedCommitHooks, scopedRollbackHooks)=>{
+                    // Savepoints on one connection form a stack: a scope holds at most
+                    // one open savepoint, and nesting goes through that savepoint's
+                    // own provider.
+                    let savepointOpen = false;
+                    const provider = {
+                        getStore: async (name)=>{
+                            if (!txStoreAPIs.has(name)) {
+                                const store = this.#stores.get(name);
+                                if (store == null) {
+                                    throw new Error(`Store "${name}" is not registered`);
+                                }
+                                txStoreAPIs.set(name, store.createAPI(txKysely, this.#adapter));
+                            }
+                            return txStoreAPIs.get(name);
+                        },
+                        hasStore: (name)=>this.#stores.has(name),
+                        onCommit: (hook)=>{
+                            scopedCommitHooks.push(hook);
+                        },
+                        onRollback: (hook)=>{
+                            scopedRollbackHooks.push(hook);
+                        },
+                        withTransaction: async (nestedFn)=>{
+                            // Already inside a transaction — Kysely does not nest.
+                            // Run `nestedFn` inline with the same provider so its hooks and
+                            // writes remain within the enclosing transaction or savepoint.
+                            return await nestedFn(provider);
+                        },
+                        withSavepoint: async (nestedFn)=>{
+                            if (savepointOpen) throw new SavepointOverlapError();
+                            savepointOpen = true;
+                            try {
+                                const name = `${this.#tablePrefix}_sp_${++savepointID}`;
+                                const savepointCommitHooks = [];
+                                const savepointRollbackHooks = [];
+                                const scopedProvider = createScopedProvider(savepointCommitHooks, savepointRollbackHooks);
+                                await sql.raw(`SAVEPOINT ${name}`).execute(trx);
+                                try {
+                                    const value = await nestedFn(scopedProvider);
+                                    await sql.raw(`RELEASE SAVEPOINT ${name}`).execute(trx);
+                                    scopedCommitHooks.push(...savepointCommitHooks);
+                                    scopedRollbackHooks.push(...savepointRollbackHooks);
+                                    return value;
+                                } catch (error) {
+                                    await sql.raw(`ROLLBACK TO SAVEPOINT ${name}`).execute(trx);
+                                    await sql.raw(`RELEASE SAVEPOINT ${name}`).execute(trx);
+                                    this.#runHooks(savepointRollbackHooks, 'rollback');
+                                    throw error;
+                                }
+                            } finally{
+                                savepointOpen = false;
+                            }
+                        }
+                    };
+                    return provider;
+                };
+                return await fn(createScopedProvider(commitHooks, rollbackHooks));
+            });
+        } catch (err) {
+            // Kysely issues ROLLBACK and rejects `execute()` when the callback
+            // throws, so the DB is already reverted here. Run the rollback hooks to
+            // drop any in-memory state that was eagerly advanced expecting a commit
+            // (revert first, then drop the stale cache). Hooks are isolated/logged,
+            // never re-thrown; the original error is preserved so callers (e.g. the
+            // engine's `MutateGraphWriteRollback` sentinel) still observe it.
+            this.#runHooks(rollbackHooks, 'rollback');
+            throw err;
+        }
+        // The transaction has committed; post-commit hooks are best-effort side
+        // effects (event emission, cache invalidation). A throwing hook must not
+        // skip the remaining hooks or make the caller observe a durable write as a
+        // failure, so each hook is isolated and its error logged, never re-thrown.
+        this.#runHooks(commitHooks, 'commit');
+        return result;
+    }
+    #runHooks(hooks, phase) {
+        for (const [index, hook] of hooks.entries()){
+            try {
+                hook();
+            } catch (error) {
+                this.#logger.error(`${phase} hook {index}/{count} failed`, {
+                    index,
+                    count: hooks.length,
+                    error
+                });
+            }
+        }
+    }
+    async migrate() {
+        this.#assertOpen();
+        await this.#ensurePreflight();
+        await Promise.all(Array.from(this.#stores.keys()).map((name)=>this.#ensureMigrated(name)));
+    }
+    close() {
+        this.#closed = true;
+        this.#closing ??= this.#close();
+        return this.#closing;
+    }
+    async #close() {
+        try {
+            await this.#db.destroy();
+        } finally{
+            await this.#adapter.close?.();
+        }
+        this.#logger.info('closed');
+    }
+    #assertOpen() {
+        if (this.#closed) throw new HozonDBClosedError();
+    }
+    #getMigrations(store) {
+        let migrations = this.#migrations.get(store.name);
+        if (migrations == null) {
+            const storeMigrations = typeof store.migrations === 'function' ? store.migrations({
+                tablePrefix: this.#tablePrefix,
+                kind: this.#adapter.kind,
+                types: this.#adapter.types,
+                functions: this.#adapter.functions
+            }) : store.migrations;
+            const plugin = new TablePrefixPlugin(this.#tablePrefix);
+            migrations = Object.fromEntries(Object.entries(storeMigrations).map(([name, migration])=>{
+                const down = migration.down;
+                return [
+                    name,
+                    {
+                        up: (db)=>migration.up(db.withPlugin(plugin)),
+                        down: down && ((db)=>down.call(migration, db.withPlugin(plugin)))
+                    }
+                ];
+            }));
+            this.#migrations.set(store.name, migrations);
+        }
+        return migrations;
+    }
+    #ensurePreflight() {
+        // Snapshot before awaiting so concurrent triggers share one read-only gate.
+        // A failed attempt clears the gate so the next caller reruns the read-only checks,
+        // then preparation; a successful attempt stays cached.
+        if (this.#preflight == null) {
+            const attempt = this.#runPreflight(Array.from(this.#stores.values())).catch((err)=>{
+                if (this.#preflight === attempt) this.#preflight = null;
+                throw err;
+            });
+            this.#preflight = attempt;
+        }
+        return this.#preflight;
+    }
+    async #runPreflight(stores) {
+        for (const store of stores){
+            await checkStore(this.#db, this.#tablePrefix, store.name, Object.keys(this.#getMigrations(store)));
+            this.#checked.add(store.name);
+        }
+        this.#assertOpen();
+        await this.#adapter.prepare?.();
+    }
+    async #ensureMigrated(name) {
+        let pending = this.#migrated.get(name);
+        if (pending == null) {
+            pending = this.#runStoreMigrations(name).catch((err)=>{
+                this.#migrated.delete(name);
+                throw err;
+            });
+            this.#migrated.set(name, pending);
+        }
+        return pending;
+    }
+    async #runStoreMigrations(name) {
+        const store = this.#stores.get(name);
+        if (store == null) {
+            throw new Error(`Store "${name}" is not registered`);
+        }
+        this.#assertOpen();
+        const migrations = this.#getMigrations(store);
+        if (!this.#checked.has(name)) {
+            await checkStore(this.#db, this.#tablePrefix, name, Object.keys(migrations));
+            this.#checked.add(name);
+        }
+        for (const dep of store.dependsOn ?? []){
+            await this.#ensureMigrated(dep);
+        }
+        this.#assertOpen();
+        if (Object.keys(migrations).length === 0) {
+            return;
+        }
+        const migrator = new Migrator({
+            db: this.#db,
+            provider: {
+                getMigrations: ()=>Promise.resolve(migrations)
+            },
+            migrationTableName: `${this.#tablePrefix}_${name}_migration`,
+            migrationLockTableName: `${this.#tablePrefix}_${name}_migration_lock`
+        });
+        const result = await migrator.migrateToLatest();
+        if (result.error != null) {
+            throw result.error;
+        }
+        this.#logger.info('store {name} migrations complete', {
+            name
+        });
+    }
+}

package/lib/dialect.d.ts

@@ -0,0 +1,3 @@
+import type { Dialect } from 'kysely';
+/** Wraps a SQLite dialect so Kysely's Migrator runs each migration run in a transaction. */
+export declare function withTransactionalDDL(dialect: Dialect): Dialect;

package/lib/dialect.js

@@ -0,0 +1,58 @@
+/**
+ * Delegates to a SQLite dialect adapter but reports transactional DDL support.
+ *
+ * Kysely's SQLite adapters report `supportsTransactionalDdl = false`, so its Migrator runs
+ * SQLite migrations outside a transaction and a failed migration leaves partial schema
+ * behind. SQLite does support transactional DDL, so HozonDB opts in for every SQLite
+ * driver regardless of which dialect it supplies.
+ */ class TransactionalDDLAdapter {
+    #adapter;
+    constructor(adapter){
+        this.#adapter = adapter;
+    }
+    get supportsCreateIfNotExists() {
+        return this.#adapter.supportsCreateIfNotExists;
+    }
+    get supportsMultipleConnections() {
+        return this.#adapter.supportsMultipleConnections;
+    }
+    get supportsTransactionalDdl() {
+        return true;
+    }
+    get supportsReturning() {
+        return this.#adapter.supportsReturning;
+    }
+    get supportsOutput() {
+        return this.#adapter.supportsOutput;
+    }
+    // biome-ignore lint/suspicious/noExplicitAny: matches Kysely's DialectAdapter signature.
+    acquireMigrationLock(db, options) {
+        return this.#adapter.acquireMigrationLock(db, options);
+    }
+    // biome-ignore lint/suspicious/noExplicitAny: matches Kysely's DialectAdapter signature.
+    releaseMigrationLock(db, options) {
+        return this.#adapter.releaseMigrationLock(db, options);
+    }
+}
+class TransactionalDDLDialect {
+    #dialect;
+    constructor(dialect){
+        this.#dialect = dialect;
+    }
+    createAdapter() {
+        return new TransactionalDDLAdapter(this.#dialect.createAdapter());
+    }
+    createDriver() {
+        return this.#dialect.createDriver();
+    }
+    // biome-ignore lint/suspicious/noExplicitAny: matches Kysely's Dialect signature.
+    createIntrospector(db) {
+        return this.#dialect.createIntrospector(db);
+    }
+    createQueryCompiler() {
+        return this.#dialect.createQueryCompiler();
+    }
+}
+/** Wraps a SQLite dialect so Kysely's Migrator runs each migration run in a transaction. */ export function withTransactionalDDL(dialect) {
+    return new TransactionalDDLDialect(dialect);
+}

package/lib/errors.d.ts

@@ -0,0 +1,12 @@
+export declare class SavepointOverlapError extends Error {
+    constructor();
+}
+export declare class SchemaVersionError extends Error {
+    constructor(store: string, unknown: Array<string>);
+}
+export declare class InvalidTablePrefixError extends Error {
+    constructor(prefix: string);
+}
+export declare class HozonDBClosedError extends Error {
+    constructor();
+}

package/lib/errors.js

@@ -0,0 +1,24 @@
+export class SavepointOverlapError extends Error {
+    constructor(){
+        super('A savepoint is already open in this transaction scope');
+        this.name = 'SavepointOverlapError';
+    }
+}
+export class SchemaVersionError extends Error {
+    constructor(store, unknown){
+        super(`Database schema for store "${store}" is newer than this version supports (unknown migrations: ${unknown.join(', ')})`);
+        this.name = 'SchemaVersionError';
+    }
+}
+export class InvalidTablePrefixError extends Error {
+    constructor(prefix){
+        super(`Invalid table prefix "${prefix}": expected /^[a-z][a-z0-9_]{0,30}$/`);
+        this.name = 'InvalidTablePrefixError';
+    }
+}
+export class HozonDBClosedError extends Error {
+    constructor(){
+        super('HozonDB is closed');
+        this.name = 'HozonDBClosedError';
+    }
+}

package/lib/index.d.ts

@@ -0,0 +1,6 @@
+export type { HozonDBParams, MigrationContext, StoreDefinition, StoreProvider } from './db.js';
+export { HozonDB } from './db.js';
+export { HozonDBClosedError, InvalidTablePrefixError, SavepointOverlapError, SchemaVersionError, } from './errors.js';
+export { chunk, withKeepSet } from './keep-set.js';
+export { withStoreTransaction } from './store-transaction.js';
+export { TablePrefixPlugin } from './table-prefix.js';

package/lib/index.js

@@ -0,0 +1,5 @@
+export { HozonDB } from './db.js';
+export { HozonDBClosedError, InvalidTablePrefixError, SavepointOverlapError, SchemaVersionError } from './errors.js';
+export { chunk, withKeepSet } from './keep-set.js';
+export { withStoreTransaction } from './store-transaction.js';
+export { TablePrefixPlugin } from './table-prefix.js';

package/lib/keep-set.d.ts

@@ -0,0 +1,19 @@
+import type { Kysely, SelectQueryBuilder } from 'kysely';
+export declare function chunk<T>(items: Array<T>, size?: number): Array<Array<T>>;
+type KeepTable = {
+    keep: {
+        trace_id: string;
+    };
+};
+/**
+ * Runs `fn` with a temporary keep table filled with `ids`, dropping it afterwards.
+ * Requires a transaction. Concurrent calls on the same transaction and table are
+ * serialized in call order; `fn` must not call `withKeepSet` for the same table.
+ */
+export declare function withKeepSet<DB, R>(db: Kysely<DB>, params: {
+    table: string;
+    ids: Array<string>;
+}, fn: (selectKeep: () => SelectQueryBuilder<KeepTable, 'keep', {
+    trace_id: string;
+}>) => Promise<R>): Promise<R>;
+export {};

package/lib/keep-set.js

@@ -0,0 +1,67 @@
+import { sql } from 'kysely';
+export function chunk(items, size = 500) {
+    if (!Number.isInteger(size) || size <= 0) throw new RangeError('Chunk size must be a positive integer');
+    const chunks = [];
+    for(let offset = 0; offset < items.length; offset += size){
+        chunks.push(items.slice(offset, offset + size));
+    }
+    return chunks;
+}
+// Per-transaction keep-set locks, keyed by table name. Store operations reuse the
+// caller's transaction (see withStoreTransaction), so concurrent calls sharing one
+// transaction would otherwise create the same temp table twice. Each call waits for
+// the previous holder of that (transaction, table) pair, in call order.
+const keepSetLocks = new WeakMap();
+async function withKeepSetLock(trx, table, fn) {
+    let locks = keepSetLocks.get(trx);
+    if (locks == null) {
+        locks = new Map();
+        keepSetLocks.set(trx, locks);
+    }
+    const previous = locks.get(table) ?? Promise.resolve();
+    let release;
+    const current = new Promise((resolve)=>{
+        release = resolve;
+    });
+    const tail = previous.then(()=>current);
+    locks.set(table, tail);
+    await previous;
+    try {
+        return await fn();
+    } finally{
+        release();
+        if (locks.get(table) === tail) locks.delete(table);
+    }
+}
+/**
+ * Runs `fn` with a temporary keep table filled with `ids`, dropping it afterwards.
+ * Requires a transaction. Concurrent calls on the same transaction and table are
+ * serialized in call order; `fn` must not call `withKeepSet` for the same table.
+ */ export async function withKeepSet(db, params, fn) {
+    if (!db.isTransaction) throw new Error('withKeepSet requires a transaction');
+    return withKeepSetLock(db, params.table, ()=>runKeepSet(db, params, fn));
+}
+async function runKeepSet(db, params, fn) {
+    await sql`CREATE TEMP TABLE ${sql.table(params.table)} (trace_id text PRIMARY KEY)`.execute(db);
+    let failed = false;
+    try {
+        const keepDB = db;
+        for (const ids of chunk(params.ids)){
+            await keepDB.insertInto(params.table).values(ids.map((traceID)=>({
+                    trace_id: traceID
+                }))).onConflict((conflict)=>conflict.doNothing()).execute();
+        }
+        return await fn(()=>keepDB.selectFrom(`${params.table} as keep`).select('trace_id'));
+    } catch (error) {
+        failed = true;
+        throw error;
+    } finally{
+        try {
+            await sql`DROP TABLE ${sql.table(params.table)}`.execute(db);
+        } catch (error) {
+            // Cleanup must not replace the primary failure, including an aborted transaction.
+            // biome-ignore lint/correctness/noUnsafeFinally: Surface cleanup failure only without a primary failure.
+            if (!failed) throw error;
+        }
+    }
+}

package/lib/preflight.d.ts

@@ -0,0 +1,2 @@
+import type { Kysely } from 'kysely';
+export declare function checkStore<DB>(db: Kysely<DB>, prefix: string, name: string, keys: Array<string>): Promise<void>;

package/lib/preflight.js

@@ -0,0 +1,18 @@
+import { sql } from 'kysely';
+import { SchemaVersionError } from './errors.js';
+export async function checkStore(db, prefix, name, keys) {
+    let rows;
+    try {
+        const result = await sql`SELECT name FROM ${sql.table(`${prefix}_${name}_migration`)}`.execute(db);
+        rows = result.rows;
+    } catch (error) {
+        // Only a missing table is a fresh schema. Connection and permission errors must surface.
+        if (error instanceof Error && ('code' in error && error.code === '42P01' || /no such table:/i.test(error.message))) {
+            return;
+        }
+        throw error;
+    }
+    const known = new Set(keys);
+    const unknown = rows.map((row)=>row.name).filter((key)=>!known.has(key)).sort();
+    if (unknown.length > 0) throw new SchemaVersionError(name, unknown);
+}

package/lib/store-transaction.d.ts

@@ -0,0 +1,2 @@
+import type { Kysely } from 'kysely';
+export declare function withStoreTransaction<DB, R>(db: Kysely<DB>, fn: (trx: Kysely<DB>) => Promise<R>): Promise<R>;

package/lib/store-transaction.js

@@ -0,0 +1,3 @@
+export async function withStoreTransaction(db, fn) {
+    return db.isTransaction ? fn(db) : db.transaction().execute(fn);
+}

package/lib/table-prefix.d.ts

@@ -0,0 +1,7 @@
+import type { KyselyPlugin, PluginTransformQueryArgs, PluginTransformResultArgs, QueryResult, RootOperationNode, UnknownRow } from 'kysely';
+export declare class TablePrefixPlugin implements KyselyPlugin {
+    #private;
+    constructor(prefix: string);
+    transformQuery({ node, queryId }: PluginTransformQueryArgs): RootOperationNode;
+    transformResult({ result }: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>>;
+}

package/lib/table-prefix.js

@@ -0,0 +1,247 @@
+import { AliasNode, IdentifierNode, JoinNode, ListNode, OperationNodeTransformer, SchemableIdentifierNode, TableNode, UsingNode } from 'kysely';
+// Kysely's root-node guard is internal; keep this list checked against its public root union.
+const ROOT_NODE_KINDS = {
+    AlterTableNode: true,
+    AlterTypeNode: true,
+    CreateIndexNode: true,
+    CreateSchemaNode: true,
+    CreateTableNode: true,
+    CreateTypeNode: true,
+    CreateViewNode: true,
+    DeleteQueryNode: true,
+    DropIndexNode: true,
+    DropSchemaNode: true,
+    DropTableNode: true,
+    DropTypeNode: true,
+    DropViewNode: true,
+    InsertQueryNode: true,
+    MergeQueryNode: true,
+    RawNode: true,
+    RefreshMaterializedViewNode: true,
+    SelectQueryNode: true,
+    UpdateQueryNode: true
+};
+function isRootOperationNode(node) {
+    return Object.hasOwn(ROOT_NODE_KINDS, node.kind);
+}
+class TablePrefixTransformer extends OperationNodeTransformer {
+    #prefix;
+    #tables = new Set();
+    #ctes = new Set();
+    #aliases = new Set();
+    #writeTargets = new Set();
+    #writeNames = new Set();
+    #prefixedIdentifiers = new WeakSet();
+    constructor(prefix){
+        super();
+        this.#prefix = prefix;
+    }
+    transformNodeImpl(node, queryId) {
+        if (!isRootOperationNode(node) || node.kind === 'RawNode' && this.nodeStack.length > 1) {
+            return super.transformNodeImpl(node, queryId);
+        }
+        return this.#transformScope(node, queryId);
+    }
+    #transformScope(node, queryId) {
+        const previousTables = this.#tables;
+        const previousCTEs = this.#ctes;
+        const previousAliases = this.#aliases;
+        const previousWriteTargets = this.#writeTargets;
+        const previousWriteNames = this.#writeNames;
+        this.#tables = new Set(previousTables);
+        this.#ctes = new Set(previousCTEs);
+        this.#aliases = new Set(previousAliases);
+        this.#writeTargets = new Set();
+        this.#writeNames = new Set(previousWriteNames);
+        try {
+            let withNode;
+            if ('with' in node && node.with) {
+                withNode = this.#transformWithScope(node.with, queryId);
+            }
+            this.#collectTables(node);
+            this.#collectWriteTargets(node);
+            const transformed = super.transformNodeImpl(withNode ? {
+                ...node,
+                with: undefined
+            } : node, queryId);
+            return withNode ? {
+                ...transformed,
+                with: withNode
+            } : transformed;
+        } finally{
+            // Nested queries inherit visible names without leaking them back into the outer query.
+            this.#tables = previousTables;
+            this.#ctes = previousCTEs;
+            this.#aliases = previousAliases;
+            this.#writeTargets = previousWriteTargets;
+            this.#writeNames = previousWriteNames;
+        }
+    }
+    transformTable(node, queryId) {
+        // Revisit plugged subqueries for correlated references, but keep their physical tables.
+        // Kysely transformers clone containers but retain immutable identifier leaves.
+        if (this.#prefixedIdentifiers.has(node.table.identifier)) return node;
+        const name = node.table.identifier.name;
+        if (this.#ctes.has(name) && !this.#writeTargets.has(node.table.identifier)) {
+            return super.transformTable(node, queryId);
+        }
+        return this.#prefixTable(node);
+    }
+    #prefixTable(node) {
+        if (node.table.schema !== undefined || this.#prefixedIdentifiers.has(node.table.identifier)) return node;
+        const name = node.table.identifier.name;
+        const transformed = TableNode.create(`${this.#prefix}_${name}`);
+        this.#prefixedIdentifiers.add(transformed.table.identifier);
+        return transformed;
+    }
+    transformReference(node, queryId) {
+        return {
+            ...node,
+            column: this.transformNode(node.column, queryId),
+            table: node.table && this.#tables.has(node.table.table.identifier.name) && !this.#aliases.has(node.table.table.identifier.name) ? this.#writeNames.has(node.table.table.identifier.name) ? this.#prefixTable(node.table) : this.transformNode(node.table, queryId) : node.table
+        };
+    }
+    transformSelectModifier(node, queryId) {
+        return {
+            ...super.transformSelectModifier({
+                ...node,
+                of: undefined
+            }, queryId),
+            of: node.of?.map((item)=>this.#transformTableReference(item, queryId))
+        };
+    }
+    transformAggregateFunction(node, queryId) {
+        return {
+            ...super.transformAggregateFunction({
+                ...node,
+                aggregated: []
+            }, queryId),
+            aggregated: this.#transformTableArgs(node.func, node.aggregated, queryId)
+        };
+    }
+    transformFunction(node, queryId) {
+        return {
+            ...super.transformFunction({
+                ...node,
+                arguments: []
+            }, queryId),
+            arguments: this.#transformTableArgs(node.func, node.arguments, queryId)
+        };
+    }
+    #transformTableArgs(func, args, queryId) {
+        return func === 'json_agg' || func === 'to_json' ? args.map((arg)=>this.#transformTableReference(arg, queryId)) : this.transformNodeList(args, queryId);
+    }
+    #transformTableReference(node, queryId) {
+        // Only direct table references can be aliases; raw sql.table() nodes still name physical tables.
+        return TableNode.is(node) && node.table.schema === undefined && this.#aliases.has(node.table.identifier.name) ? node : this.transformNode(node, queryId);
+    }
+    #collectTables(node) {
+        this.#collectRawTables(node);
+        if ('name' in node && node.name && SchemableIdentifierNode.is(node.name)) {
+            this.#tables.add(node.name.identifier.name);
+        }
+        if ('from' in node && node.from) {
+            for (const table of node.from.froms)this.#collectTableExpression(table);
+        }
+        if ('into' in node && node.into) this.#collectTableExpression(node.into);
+        if ('table' in node && node.table) this.#collectTableExpression(node.table);
+        if ('joins' in node && node.joins) {
+            for (const join of node.joins)this.#collectTableExpression(join.table);
+        }
+        if ('using' in node && node.using) {
+            this.#collectTableExpression(JoinNode.is(node.using) ? node.using.table : node.using);
+        }
+    }
+    #transformWithScope(node, queryId) {
+        // Nonrecursive definitions see preceding CTEs, not their own name or later names.
+        if (node.recursive) {
+            for (const expression of node.expressions){
+                this.#ctes.add(expression.name.table.table.identifier.name);
+            }
+        }
+        const expressions = [];
+        for (const expression of node.expressions){
+            expressions.push({
+                ...expression,
+                expression: expression.expression.kind === 'RawNode' ? Object.freeze(this.#transformScope(expression.expression, queryId)) : this.transformNode(expression.expression, queryId)
+            });
+            this.#ctes.add(expression.name.table.table.identifier.name);
+        }
+        return {
+            ...node,
+            expressions
+        };
+    }
+    #collectWriteTargets(node) {
+        const collect = (table)=>{
+            if (TableNode.is(table)) {
+                this.#writeTargets.add(table.table.identifier);
+                this.#writeNames.add(table.table.identifier.name);
+            } else if (AliasNode.is(table)) {
+                collect(table.node);
+            } else if (ListNode.is(table)) {
+                for (const item of table.items)collect(item);
+            }
+        };
+        if (node.kind === 'InsertQueryNode' || node.kind === 'MergeQueryNode') {
+            if (node.into) collect(node.into);
+        } else if (node.kind === 'UpdateQueryNode') {
+            if (node.table) collect(node.table);
+        } else if (node.kind === 'DeleteQueryNode') {
+            for (const table of node.from.froms)collect(table);
+        }
+    }
+    #collectRawTables(node) {
+        // Qualifiers are references, not declarations. Nested queries collect their own scope.
+        if (node.kind === 'ReferenceNode' || node.kind === 'WithNode') return;
+        if (node.kind === 'RawNode') {
+            for (const parameter of node.parameters){
+                if (AliasNode.is(parameter)) {
+                    if (!isRootOperationNode(parameter.node) || parameter.node.kind === 'RawNode') this.#collectRawTables(parameter.node);
+                    this.#collectTableExpression(parameter);
+                    continue;
+                }
+                this.#collectTableExpression(parameter);
+                if (!isRootOperationNode(parameter) || parameter.kind === 'RawNode') this.#collectRawTables(parameter);
+            }
+            return;
+        }
+        for (const value of Object.values(node)){
+            for (const child of Array.isArray(value) ? value : [
+                value
+            ]){
+                if (child && typeof child === 'object' && 'kind' in child) {
+                    const operation = child;
+                    if (!isRootOperationNode(operation) || operation.kind === 'RawNode') this.#collectRawTables(operation);
+                }
+            }
+        }
+    }
+    #collectTableExpression(node) {
+        if (TableNode.is(node)) {
+            this.#tables.add(node.table.identifier.name);
+            this.#aliases.delete(node.table.identifier.name);
+            // Local read bindings shadow enclosing write qualifiers in correlated subqueries.
+            this.#writeNames.delete(node.table.identifier.name);
+        } else if (AliasNode.is(node)) {
+            if (TableNode.is(node.node)) this.#tables.add(node.node.table.identifier.name);
+            if (IdentifierNode.is(node.alias)) this.#aliases.add(node.alias.name);
+        } else if (ListNode.is(node)) {
+            for (const table of node.items)this.#collectTableExpression(table);
+        } else if (UsingNode.is(node)) {
+            for (const table of node.tables)this.#collectTableExpression(table);
+        }
+    }
+}
+export class TablePrefixPlugin {
+    #transformer;
+    constructor(prefix){
+        this.#transformer = new TablePrefixTransformer(prefix);
+    }
+    transformQuery({ node, queryId }) {
+        return this.#transformer.transformNode(node, queryId);
+    }
+    async transformResult({ result }) {
+        return result;
+    }
+}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@hozon/db",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Database registry, migrations and transactions for Hozon",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TairuFramework/hozon.git",
+    "directory": "packages/db"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "lib/*"
+  ],
+  "dependencies": {
+    "@hozon/adapter": "^0.1.0",
+    "@sozai/log": "^0.4.0",
+    "kysely": "^0.29.6"
+  },
+  "devDependencies": {
+    "@hozon/node-sqlite": "^0.1.0",
+    "@types/node": "^26.6.4",
+    "del-cli": "^7.0.0",
+    "vitest": "5.0.3"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "build:clean": "del-cli lib",
+    "build:js": "del-cli \"lib/**/*.js\" && swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
+    "build:types": "del-cli \"lib/**/*.d.ts\" \"lib/**/*.d.ts.map\" && tsc --emitDeclarationOnly --skipLibCheck",
+    "build:types:ci": "tsc --emitDeclarationOnly --skipLibCheck --declarationMap false",
+    "test": "pnpm run test:types && pnpm run test:unit",
+    "test:types": "tsc --noEmit --skipLibCheck -p tsconfig.test.json",
+    "test:unit": "vitest run"
+  }
 }