@hozon/db 0.0.0-stage → 0.1.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,78 @@
+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 = {
+    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,286 @@
+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';
+export class HozonDB {
+    #tablePrefix;
+    #closed = false;
+    #closing = null;
+    #preflight = null;
+    #checked = new Set();
+    #migrations = new Map();
+    #adapter;
+    #db;
+    #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.#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.#db, 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.#db.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) {
+            migrations = typeof store.migrations === 'function' ? store.migrations({
+                kind: this.#adapter.kind,
+                types: this.#adapter.types,
+                functions: this.#adapter.functions
+            }) : store.migrations;
+            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,5 @@
+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';

package/lib/index.js

@@ -0,0 +1,4 @@
+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';

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/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.1.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"
+  }
 }