@kumiai/hub-store 0.0.0-stage → 0.10.0

package/README.md

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# @kumiai/hub-store
 
-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.
+A SQL `HubStore` for Kumiai hubs, registered as a Hozon store. It runs on any Hozon adapter
+(node:sqlite, Postgres) and passes the `@kumiai/hub-conformance` suites on both.
+
+Use `@kumiai/hub-http` to host a hub over HTTP. Use this package directly when composing a hub
+server with a custom transport or when you need the store API separately.
+
+## Exports
+
+- `createHubStoreDefinition(options?)` -- the Hozon `StoreDefinition`, named `'kumiai-hub'`
+  (`HUB_STORE`).
+- `getHubStore(provider)` -- the `HubStore` from a `HozonDB` or any Hozon `StoreProvider`.
+- `HubStoreOptions`.
+
+```ts
+import { HozonDB } from '@hozon/db'
+import { NodeSQLiteAdapter } from '@hozon/node-sqlite'
+import { createHubStoreDefinition, getHubStore } from '@kumiai/hub-store'
+
+const db = new HozonDB({ adapter: new NodeSQLiteAdapter({ database: 'hub.db' }) })
+db.register(createHubStoreDefinition({ maxRetention: 30 * 24 * 60 * 60, maxDepth: 1000 }))
+const store = await getHubStore(db)
+```
+
+The database applies the store migrations when `getHubStore` first resolves the registered
+definition. Close the `HozonDB` when the host shuts down.
+
+## Options
+
+| Option | Default | Meaning |
+|--------|---------|---------|
+| `defaultRetention` | `0` | Floor, in seconds, on how long a topic's frames are kept. |
+| `maxRetention` | `2592000` (30 days) | Ceiling, in seconds, a subscribe may request. Above it the subscribe is refused. |
+| `maxDepth` | `1000` | Retained log frames per topic. The oldest log frames are evicted first. |
+| `maxKeyPackagesPerDID` | `100` | Ordinary key packages one DID may hold. An upload past it is refused. |
+| `maxSubscriptionsPerDID` | `1000` | Distinct topics one DID may subscribe to. |
+
+Set `maxRetention` or `maxDepth` to `Infinity` to disable that bound explicitly.
+These defaults match the memory store. Periodic purge applies the age policy.
+
+## Storage
+
+The migrations name tables without a prefix (`hub_messages`, `hub_topics`, ...). `HozonDB` applies
+its `tablePrefix`, so several hubs can share one database under different prefixes.
+
+`publish` claims the publish ID, then runs the head compare-and-set, sequence mint, append and the
+head advance in one transaction. The head advance is a conditional write, so two hub processes on
+one Postgres database cannot both accept a publish at the same head.
+
+Concurrent retries of one publish ID wait for the accepting transaction and return its sequence ID with `deduped: true`.

package/lib/definition.d.ts

@@ -0,0 +1,7 @@
+import type { StoreDefinition, StoreProvider } from '@hozon/db';
+import type { HubStore } from '@kumiai/hub-protocol';
+import { type HubStoreOptions } from './store.js';
+import type { HubTables } from './tables.js';
+export declare const HUB_STORE = "kumiai-hub";
+export declare function createHubStoreDefinition(options?: HubStoreOptions): StoreDefinition<HubTables, HubStore>;
+export declare function getHubStore(provider: StoreProvider): Promise<HubStore>;

package/lib/definition.js

@@ -0,0 +1,17 @@
+import { hubStoreMigrations } from './migrations.js';
+import { createHubStore } from './store.js';
+export const HUB_STORE = 'kumiai-hub';
+export function createHubStoreDefinition(options = {}) {
+    return {
+        name: HUB_STORE,
+        migrations: hubStoreMigrations,
+        createAPI: (db, adapter)=>createHubStore({
+                db,
+                adapter,
+                options
+            })
+    };
+}
+export async function getHubStore(provider) {
+    return await provider.getStore(HUB_STORE);
+}

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export { createHubStoreDefinition, getHubStore, HUB_STORE } from './definition.js';
+export type { HubStoreOptions } from './store.js';

package/lib/index.js

@@ -0,0 +1 @@
+export { createHubStoreDefinition, getHubStore, HUB_STORE } from './definition.js';

package/lib/migrations.d.ts

@@ -0,0 +1,2 @@
+import type { Migration, MigrationContext } from '@hozon/db';
+export declare function hubStoreMigrations(ctx: MigrationContext): Record<string, Migration>;

package/lib/migrations.js

@@ -0,0 +1,59 @@
+export function hubStoreMigrations(ctx) {
+    const t = ctx.types;
+    const p = ctx.tablePrefix;
+    return {
+        '0-init': {
+            async up (db) {
+                await db.schema.createTable('hub_messages').addColumn('sequence_id', t.text, (col)=>col.notNull().primaryKey()).addColumn('sender_did', t.text, (col)=>col.notNull()).addColumn('topic_id', t.text, (col)=>col.notNull()).addColumn('payload', t.binary, (col)=>col.notNull()).addColumn('stored_at', t.bigint, (col)=>col.notNull()).addColumn('retain', t.text, (col)=>col.notNull().defaultTo('mailbox')).execute();
+                await db.schema.createIndex(`${p}_hub_messages_topic`).on('hub_messages').columns([
+                    'topic_id',
+                    'retain',
+                    'sequence_id'
+                ]).execute();
+                await db.schema.createTable('hub_deliveries').addColumn('sequence_id', t.text, (col)=>col.notNull()).addColumn('recipient_did', t.text, (col)=>col.notNull()).addPrimaryKeyConstraint(`${p}_hub_deliveries_pk`, [
+                    'sequence_id',
+                    'recipient_did'
+                ]).execute();
+                await db.schema.createIndex(`${p}_hub_deliveries_recipient`).on('hub_deliveries').column('recipient_did').execute();
+                await db.schema.createTable('hub_key_packages').addColumn('id', t.serial, (col)=>col.primaryKey()).addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('key_package', t.text, (col)=>col.notNull()).addColumn('not_after', t.bigint).execute();
+                await db.schema.createIndex(`${p}_hub_key_packages_owner`).on('hub_key_packages').column('owner_did').execute();
+                // The primary key is what holds "one last-resort slot per owner".
+                await db.schema.createTable('hub_last_resort_key_packages').addColumn('owner_did', t.text, (col)=>col.notNull().primaryKey()).addColumn('key_package', t.text, (col)=>col.notNull()).execute();
+                await db.schema.createTable('hub_subscriptions').addColumn('topic_id', t.text, (col)=>col.notNull()).addColumn('subscriber_did', t.text, (col)=>col.notNull()).addColumn('last_active_at', t.bigint, (col)=>col.notNull().defaultTo(0)).addColumn('retention', t.bigint, (col)=>col.notNull().defaultTo(0)).addPrimaryKeyConstraint(`${p}_hub_subscriptions_pk`, [
+                    'topic_id',
+                    'subscriber_did'
+                ]).execute();
+                await db.schema.createIndex(`${p}_hub_subscriptions_subscriber`).on('hub_subscriptions').columns([
+                    'subscriber_did'
+                ]).execute();
+                await db.schema.createTable('hub_topics').addColumn('topic_id', t.text, (col)=>col.notNull().primaryKey()).addColumn('head', t.text, (col)=>col.notNull()).addColumn('removed_through', t.text).execute();
+                // Persisted, not derived from surviving frames, so emptying a topic never regresses
+                // minting below a head the topic still names. Global, so a sequenceID is unique across
+                // topics and the mailbox fetch stays globally ordered.
+                await db.schema.createTable('hub_sequence').addColumn('id', t.bigint, (col)=>col.notNull().primaryKey()).addColumn('counter', t.bigint, (col)=>col.notNull()).execute();
+                // Through the query builder, not raw SQL, so the table prefix applies.
+                await db.insertInto('hub_sequence').values({
+                    id: 0,
+                    counter: 0
+                }).execute();
+                await db.schema.createTable('hub_publish_ids').addColumn('topic_id', t.text, (col)=>col.notNull()).addColumn('publish_id', t.text, (col)=>col.notNull()).addColumn('sequence_id', t.text).addColumn('recorded_at', t.bigint, (col)=>col.notNull().defaultTo(0)).addPrimaryKeyConstraint(`${p}_hub_publish_ids_pk`, [
+                    'topic_id',
+                    'publish_id'
+                ]).execute();
+                await db.schema.createIndex(`${p}_hub_publish_ids_recorded`).on('hub_publish_ids').columns([
+                    'recorded_at'
+                ]).execute();
+            },
+            async down (db) {
+                await db.schema.dropTable('hub_publish_ids').execute();
+                await db.schema.dropTable('hub_sequence').execute();
+                await db.schema.dropTable('hub_topics').execute();
+                await db.schema.dropTable('hub_subscriptions').execute();
+                await db.schema.dropTable('hub_last_resort_key_packages').execute();
+                await db.schema.dropTable('hub_key_packages').execute();
+                await db.schema.dropTable('hub_deliveries').execute();
+                await db.schema.dropTable('hub_messages').execute();
+            }
+        }
+    };
+}

package/lib/store.d.ts

@@ -0,0 +1,31 @@
+import type { Adapter } from '@hozon/adapter';
+import { type Kysely } from '@hozon/db';
+import { type HubStore } from '@kumiai/hub-protocol';
+import type { HubTables } from './tables.js';
+export type HubStoreOptions = {
+    /** Hub default retention in seconds: the floor for a topic's age bound. Default 0. */
+    defaultRetention?: number;
+    /**
+     * Maximum retention in seconds a subscribe may request. A request above it is refused with
+     * `RetentionExceededError`, never clamped. Default 30 days; Infinity disables the maximum.
+     */
+    maxRetention?: number;
+    /**
+     * Maximum retained LOG frames per topic, oldest evicted first. Counts log frames only, so a
+     * mailbox flood cannot evict the commit log. Default 1000; Infinity disables the bound.
+     */
+    maxDepth?: number;
+    /**
+     * Maximum ordinary key packages one DID may hold. An upload past it is rejected, never evicted:
+     * eviction would let a flood push a victim's live packages out. Default 100.
+     */
+    maxKeyPackagesPerDID?: number;
+    /** Maximum distinct topics one DID may subscribe to. Default 1000. */
+    maxSubscriptionsPerDID?: number;
+};
+export type CreateHubStoreParams = {
+    db: Kysely<HubTables>;
+    adapter: Adapter;
+    options?: HubStoreOptions;
+};
+export declare function createHubStore(params: CreateHubStoreParams): HubStore;

package/lib/store.js

@@ -0,0 +1,487 @@
+import { withStoreTransaction } from '@hozon/db';
+import { HeadMismatchError, KeyPackageQuotaExceededError, NotSubscribedError, RetentionExceededError, SubscriptionQuotaExceededError } from '@kumiai/hub-protocol';
+import { EventEmitter } from '@sozai/event';
+/**
+ * How long an idempotency record outlives its own publish, in seconds.
+ *
+ * A year: past this a repeated publish is treated as new, so the window must exceed any replay a
+ * real client could still hold -- a parked commit, a device restored from backup, a lane retried
+ * after an outage. Not a host-tuned knob.
+ */ const PUBLISH_ID_RETENTION_SECONDS = 365 * 24 * 60 * 60;
+/** Frames deleted per statement: see `deleteFrames`. */ const DELETE_CHUNK_SIZE = 500;
+const DEFAULT_MAX_KEY_PACKAGES_PER_DID = 100;
+const DEFAULT_MAX_SUBSCRIPTIONS_PER_DID = 1000;
+// A DB binary column (a Buffer under node-postgres-style drivers) as a plain Uint8Array, so payload
+// equality holds against a Uint8Array caller.
+function toBytes(value) {
+    return new Uint8Array(value);
+}
+// `not_after` is seconds; every other timestamp here is milliseconds.
+function nowSeconds() {
+    return Math.floor(Date.now() / 1000);
+}
+export function createHubStore(params) {
+    const { db, adapter, options = {} } = params;
+    const defaultRetention = options.defaultRetention ?? 0;
+    const maxRetention = options.maxRetention ?? 30 * 24 * 60 * 60;
+    const maxDepth = options.maxDepth ?? 1000;
+    const maxKeyPackagesPerDID = options.maxKeyPackagesPerDID ?? DEFAULT_MAX_KEY_PACKAGES_PER_DID;
+    const maxSubscriptionsPerDID = options.maxSubscriptionsPerDID ?? DEFAULT_MAX_SUBSCRIPTIONS_PER_DID;
+    const events = new EventEmitter();
+    // One snapshot for every read of a `fetchTopic`: under Postgres' default READ COMMITTED each
+    // statement would see its own, and head, oldest, gap and messages could disagree.
+    function readSnapshot(fn) {
+        return db.isTransaction ? fn(db) : db.transaction().setIsolationLevel('repeatable read').execute(fn);
+    }
+    /**
+   * Remove frames and the deliveries pointing at them, a chunk at a time.
+   *
+   * SQLite binds one parameter per `in` element and throws "too many SQL variables" past its
+   * limit, so an unchunked sweep fails precisely when the backlog is large. Deliveries first: a
+   * delivery references a frame and cannot be pushed once its referent is gone.
+   */ async function deleteFrames(executor, sequenceIDs) {
+        for(let index = 0; index < sequenceIDs.length; index += DELETE_CHUNK_SIZE){
+            const chunk = sequenceIDs.slice(index, index + DELETE_CHUNK_SIZE);
+            await executor.deleteFrom('hub_deliveries').where('sequence_id', 'in', chunk).execute();
+            await executor.deleteFrom('hub_messages').where('sequence_id', 'in', chunk).execute();
+        }
+    }
+    // Every log removal (trim, depth, age) advances the topic's removal watermark, which is what
+    // `fetchTopic` reports a gap from. Monotonic: it never moves back.
+    async function advanceRemovedThrough(executor, topicID, sequenceID) {
+        await executor.updateTable('hub_topics').set({
+            removed_through: sequenceID
+        }).where('topic_id', '=', topicID).where((eb)=>{
+            return eb.or([
+                eb('removed_through', 'is', null),
+                eb('removed_through', '<', sequenceID)
+            ]);
+        }).execute();
+    }
+    // Take the topic's row lock before touching its frames. `publish` locks the row (head write)
+    // and only then evicts frames, so a sweep that deleted frames first and wrote the row after
+    // would take the same two locks in the opposite order and deadlock on Postgres.
+    async function lockTopic(trx, topicID) {
+        await trx.selectFrom('hub_topics').select('topic_id').where('topic_id', '=', topicID)// SQLite has no row locks (and rejects the clause); its one writer already serialises.
+        .$if(adapter.kind === 'postgres', (qb)=>qb.forUpdate()).execute();
+    }
+    // Mint the next sequenceID inside the accepting transaction, from a persistent global counter.
+    // Fixed-width zero-padded so lexicographic order matches numeric order (`"10" > "9"`).
+    //
+    // One row, so every publish on every topic serialises behind it: the cost of a single total
+    // order. It deadlocks nothing: writers claim publish IDs first, then this row, then per-topic rows.
+    async function nextSequenceID(trx) {
+        const row = await trx.updateTable('hub_sequence').set((eb)=>({
+                counter: eb('counter', '+', 1)
+            })).where('id', '=', 0).returning('counter').executeTakeFirstOrThrow();
+        return String(row.counter).padStart(12, '0');
+    }
+    // Depth eviction runs inside the publishing transaction. Counts LOG frames only. Silent: it is a
+    // synchronous consequence of the caller's own publish.
+    async function evictDepth(trx, topicID) {
+        if (maxDepth === Number.POSITIVE_INFINITY) return;
+        const logRows = await trx.selectFrom('hub_messages').select('sequence_id').where('topic_id', '=', topicID).where('retain', '=', 'log').orderBy('sequence_id', 'asc').execute();
+        if (logRows.length <= maxDepth) return;
+        const evict = logRows.slice(0, logRows.length - maxDepth).map((r)=>r.sequence_id);
+        await deleteFrames(trx, evict);
+        await advanceRemovedThrough(trx, topicID, evict[evict.length - 1]);
+    }
+    async function publish(publishParams) {
+        const retain = publishParams.retain ?? 'mailbox';
+        const { senderDID, topicID } = publishParams;
+        // The dedup check, the head compare-and-set, the sequence mint, the append, and the head
+        // advance all happen in ONE transaction, in that order. A read-then-write CAS split across
+        // statements is the exact race the head exists to eliminate.
+        return await withStoreTransaction(db, async (trx)=>{
+            // Claim before minting or CAS: a concurrent retry waits for the holder to commit.
+            if (publishParams.publishID != null) {
+                const claimed = await trx.insertInto('hub_publish_ids').values({
+                    topic_id: topicID,
+                    publish_id: publishParams.publishID,
+                    sequence_id: null,
+                    recorded_at: Date.now()
+                }).onConflict((oc)=>oc.columns([
+                        'topic_id',
+                        'publish_id'
+                    ]).doNothing()).executeTakeFirst();
+                if (Number(claimed.numInsertedOrUpdatedRows ?? 0n) === 0) {
+                    const existing = await trx.selectFrom('hub_publish_ids').select('sequence_id').where('topic_id', '=', topicID).where('publish_id', '=', publishParams.publishID).executeTakeFirstOrThrow();
+                    if (existing.sequence_id == null) throw new Error('Incomplete publish-id record');
+                    return {
+                        sequenceID: existing.sequence_id,
+                        deduped: true
+                    };
+                }
+            }
+            // 2. Stored head (null when the topic has never had an accepted log publish).
+            const topicRow = await trx.selectFrom('hub_topics').select('head').where('topic_id', '=', topicID).executeTakeFirst();
+            const currentHead = topicRow?.head ?? null;
+            // 3. Compare-and-set. On mismatch, throw and store NOTHING: the transaction rolls back.
+            if (publishParams.expectedHead !== undefined && currentHead !== publishParams.expectedHead) {
+                throw new HeadMismatchError(`head mismatch: expected ${String(publishParams.expectedHead)}, current ${String(currentHead)}`);
+            }
+            // 4. Mint the sequenceID.
+            const sequenceID = await nextSequenceID(trx);
+            // 5. Recipients = current subscribers minus the sender.
+            const subscriberRows = await trx.selectFrom('hub_subscriptions').select('subscriber_did').where('topic_id', '=', topicID).execute();
+            const recipients = subscriberRows.map((r)=>r.subscriber_did).filter((did)=>did !== senderDID);
+            // 6. Append. A log frame is stored unconditionally (its reader may not exist yet). A mailbox
+            // frame with zero recipients is not stored, but the sequenceID is still consumed.
+            if (retain === 'log' || recipients.length > 0) {
+                await trx.insertInto('hub_messages').values({
+                    sequence_id: sequenceID,
+                    sender_did: senderDID,
+                    topic_id: topicID,
+                    payload: adapter.encodeBinary(publishParams.payload),
+                    stored_at: Date.now(),
+                    retain
+                }).execute();
+                if (recipients.length > 0) {
+                    await trx.insertInto('hub_deliveries').values(recipients.map((did)=>({
+                            sequence_id: sequenceID,
+                            recipient_did: did
+                        }))).execute();
+                }
+            }
+            // 7. Advance the stored head, LOG frames only.
+            //
+            // The earlier head read is only an MVCC snapshot, which two transactions racing at the same
+            // head both pass. The arbiter is this CONDITIONAL write: the loser matches zero rows, throws,
+            // and rolls the whole transaction back.
+            if (retain === 'log') {
+                if (publishParams.expectedHead === undefined) {
+                    // Unconditional: last-writer-wins on the head pointer.
+                    await trx.insertInto('hub_topics').values({
+                        topic_id: topicID,
+                        head: sequenceID
+                    }).onConflict((oc)=>oc.column('topic_id').doUpdateSet({
+                            head: sequenceID
+                        })).execute();
+                } else if (publishParams.expectedHead === null) {
+                    // Lose to any concurrent transaction that inserted the row first (conflict: 0 rows).
+                    const inserted = await trx.insertInto('hub_topics').values({
+                        topic_id: topicID,
+                        head: sequenceID
+                    }).onConflict((oc)=>oc.column('topic_id').doNothing()).executeTakeFirst();
+                    if (Number(inserted.numInsertedOrUpdatedRows ?? 0n) === 0) {
+                        throw new HeadMismatchError('head mismatch: expected null, a concurrent publish set the head first');
+                    }
+                } else {
+                    const updated = await trx.updateTable('hub_topics').set({
+                        head: sequenceID
+                    }).where('topic_id', '=', topicID).where('head', '=', publishParams.expectedHead).executeTakeFirst();
+                    if (Number(updated.numUpdatedRows ?? 0n) === 0) {
+                        throw new HeadMismatchError(`head mismatch: expected ${publishParams.expectedHead}, a concurrent publish advanced it`);
+                    }
+                }
+                await evictDepth(trx, topicID);
+            }
+            // Complete the claim before committing; failed publishes roll the claim back.
+            if (publishParams.publishID != null) {
+                await trx.updateTable('hub_publish_ids').set({
+                    sequence_id: sequenceID
+                }).where('topic_id', '=', topicID).where('publish_id', '=', publishParams.publishID).execute();
+            }
+            return {
+                sequenceID,
+                deduped: false
+            };
+        });
+    }
+    async function fetch(fetchParams) {
+        if (fetchParams.ack != null && fetchParams.ack.length > 0) {
+            await ack({
+                recipientDID: fetchParams.recipientDID,
+                sequenceIDs: fetchParams.ack
+            });
+        }
+        let query = db.selectFrom('hub_deliveries').innerJoin('hub_messages', 'hub_messages.sequence_id', 'hub_deliveries.sequence_id').select([
+            'hub_messages.sequence_id',
+            'hub_messages.sender_did',
+            'hub_messages.topic_id',
+            'hub_messages.payload',
+            'hub_messages.retain'
+        ]).where('hub_deliveries.recipient_did', '=', fetchParams.recipientDID).orderBy('hub_messages.sequence_id', 'asc');
+        if (fetchParams.after != null) {
+            query = query.where('hub_messages.sequence_id', '>', fetchParams.after);
+        }
+        const limit = fetchParams.limit;
+        if (limit != null) {
+            // One extra row decides `hasMore`.
+            query = query.limit(limit + 1);
+        }
+        const rows = await query.execute();
+        let hasMore = false;
+        let resultRows = rows;
+        if (limit != null && rows.length > limit) {
+            hasMore = true;
+            resultRows = rows.slice(0, limit);
+        }
+        // One global sequence serves both classes, so a log frame's own sequenceID IS its log
+        // position. Omitted for a mailbox frame: a falsy placeholder is a position a cursor would move
+        // to, skipping every log frame below it.
+        const messages = resultRows.map((row)=>({
+                sequenceID: row.sequence_id,
+                senderDID: row.sender_did,
+                topicID: row.topic_id,
+                payload: toBytes(row.payload),
+                ...row.retain === 'log' ? {
+                    logPosition: row.sequence_id
+                } : {}
+            }));
+        const cursor = messages.at(-1)?.sequenceID ?? null;
+        return {
+            messages,
+            cursor,
+            hasMore
+        };
+    }
+    async function fetchTopic(fetchParams) {
+        const { subscriberDID, topicID, after } = fetchParams;
+        return await readSnapshot(async (trx)=>{
+            const subscription = await trx.selectFrom('hub_subscriptions').select('subscriber_did').where('topic_id', '=', topicID).where('subscriber_did', '=', subscriberDID).executeTakeFirst();
+            if (subscription == null) {
+                throw new NotSubscribedError(`${subscriberDID} is not subscribed to ${topicID}`);
+            }
+            const topicRow = await trx.selectFrom('hub_topics').select([
+                'head',
+                'removed_through'
+            ]).where('topic_id', '=', topicID).executeTakeFirst();
+            const head = topicRow?.head ?? null;
+            const removedThrough = topicRow?.removed_through ?? null;
+            const oldestRow = await trx.selectFrom('hub_messages').select((eb)=>eb.fn.min('sequence_id').as('oldest')).where('topic_id', '=', topicID).where('retain', '=', 'log').executeTakeFirst();
+            const oldest = oldestRow?.oldest ?? null;
+            // The log is the topic's log-class frames and NOTHING else. `limit` applies after the class
+            // filter, so a page of mailbox frames cannot hand a draining reader an empty page.
+            let query = trx.selectFrom('hub_messages').select([
+                'sequence_id',
+                'sender_did',
+                'topic_id',
+                'payload'
+            ]).where('topic_id', '=', topicID).where('retain', '=', 'log').orderBy('sequence_id', 'asc');
+            if (after != null) {
+                query = query.where('sequence_id', '>', after);
+            }
+            if (fetchParams.limit != null) {
+                query = query.limit(fetchParams.limit);
+            }
+            const rows = await query.execute();
+            const messages = rows.map((row)=>({
+                    sequenceID: row.sequence_id,
+                    senderDID: row.sender_did,
+                    topicID: row.topic_id,
+                    payload: toBytes(row.payload),
+                    logPosition: row.sequence_id
+                }));
+            // Removal is prefix-only, so a watermark past the cursor means frames the reader never saw
+            // are gone.
+            const gap = removedThrough != null && (after == null || removedThrough > after);
+            return {
+                messages,
+                head,
+                oldest,
+                gap
+            };
+        });
+    }
+    async function ack(ackParams) {
+        if (ackParams.sequenceIDs.length === 0) return;
+        await db.deleteFrom('hub_deliveries').where('recipient_did', '=', ackParams.recipientDID).where('sequence_id', 'in', ackParams.sequenceIDs).execute();
+        // GC fully-acked MAILBOX frames only. Ack frees a delivery, never a log entry or the head.
+        const withDeliveries = await db.selectFrom('hub_deliveries').select('sequence_id').where('sequence_id', 'in', ackParams.sequenceIDs).execute();
+        const stillDelivered = new Set(withDeliveries.map((r)=>r.sequence_id));
+        const fullyAcked = ackParams.sequenceIDs.filter((id)=>!stillDelivered.has(id));
+        if (fullyAcked.length > 0) {
+            await db.deleteFrom('hub_messages').where('sequence_id', 'in', fullyAcked).where('retain', '=', 'mailbox').execute();
+        }
+    }
+    async function trim(trimParams) {
+        // LOG frames strictly below the bound, and only those. The head and the publishID records are
+        // never touched.
+        await withStoreTransaction(db, async (trx)=>{
+            await lockTopic(trx, trimParams.topicID);
+            const logRows = await trx.selectFrom('hub_messages').select('sequence_id').where('topic_id', '=', trimParams.topicID).where('retain', '=', 'log').where('sequence_id', '<', trimParams.before).orderBy('sequence_id', 'asc').execute();
+            const sequenceIDs = logRows.map((r)=>r.sequence_id);
+            if (sequenceIDs.length === 0) return;
+            await deleteFrames(trx, sequenceIDs);
+            await advanceRemovedThrough(trx, trimParams.topicID, sequenceIDs.at(-1));
+        });
+    }
+    async function purge(purgeParams) {
+        const now = Date.now();
+        const olderThan = purgeParams.olderThan;
+        // Idempotency records outlive the frames they dedup, on their own clock. Without this sweep
+        // the table is the fastest-growing on a long-lived hub.
+        await db.deleteFrom('hub_publish_ids').where('recorded_at', '<=', now - PUBLISH_ID_RETENTION_SECONDS * 1000).execute();
+        const topicRows = await db.selectFrom('hub_messages').select('topic_id').distinct().orderBy('topic_id', 'asc').execute();
+        // Every topic's longest CURRENT subscriber retention in one grouped read.
+        const retentionRows = await db.selectFrom('hub_subscriptions').select((eb)=>[
+                'topic_id',
+                eb.fn.max('retention').as('maxRetention')
+            ]).groupBy('topic_id').execute();
+        const retentionByTopic = new Map(retentionRows.map((row)=>[
+                row.topic_id,
+                Number(row.maxRetention ?? 0)
+            ]));
+        // One transaction per topic: frames and that topic's watermark commit together, and row locks
+        // are held for one topic at a time, in topic_id order.
+        const removed = [];
+        for (const { topic_id } of topicRows){
+            const subscriberRetention = retentionByTopic.get(topic_id) ?? 0;
+            const effective = Math.max(olderThan, subscriberRetention, defaultRetention);
+            const threshold = now - effective * 1000;
+            const ids = await withStoreTransaction(db, async (trx)=>{
+                await lockTopic(trx, topic_id);
+                // Log removal is prefix-only by position. A clock that moved backwards can leave a due
+                // frame above one that is not; removing it would punch a hole a cursor cannot see.
+                const keptRow = await trx.selectFrom('hub_messages').select((eb)=>eb.fn.min('sequence_id').as('firstKept')).where('topic_id', '=', topic_id).where('retain', '=', 'log').where('stored_at', '>', threshold).executeTakeFirst();
+                const firstKept = keptRow?.firstKept ?? null;
+                const frames = await trx.selectFrom('hub_messages').select([
+                    'sequence_id',
+                    'retain'
+                ]).where('topic_id', '=', topic_id).where((eb)=>{
+                    return eb.or([
+                        eb.and([
+                            eb('retain', '=', 'mailbox'),
+                            eb('stored_at', '<=', threshold)
+                        ]),
+                        firstKept == null ? eb('retain', '=', 'log') : eb.and([
+                            eb('retain', '=', 'log'),
+                            eb('sequence_id', '<', firstKept)
+                        ])
+                    ]);
+                }).orderBy('sequence_id', 'asc').execute();
+                if (frames.length === 0) return [];
+                const frameIDs = frames.map((frame)=>frame.sequence_id);
+                await deleteFrames(trx, frameIDs);
+                const lastLog = frames.findLast((frame)=>frame.retain === 'log');
+                if (lastLog != null) {
+                    await advanceRemovedThrough(trx, topic_id, lastLog.sequence_id);
+                }
+                return frameIDs;
+            });
+            removed.push(...ids);
+        }
+        removed.sort();
+        if (removed.length === 0) return [];
+        await events.emit('purge', {
+            sequenceIDs: removed
+        });
+        return removed;
+    }
+    async function deleteExpiredKeyPackages(ownerDID) {
+        await db.deleteFrom('hub_key_packages').where('owner_did', '=', ownerDID).where('not_after', 'is not', null).where('not_after', '<=', nowSeconds()).execute();
+    }
+    async function storeKeyPackage({ ownerDID, keyPackage, notAfter }) {
+        // Drop the dead BEFORE charging the cap. The cap rejects rather than evicts, so nothing else
+        // would ever remove them, and a pool full of expired entries could never be replenished.
+        await deleteExpiredKeyPackages(ownerDID);
+        const row = await db.selectFrom('hub_key_packages').select((eb)=>eb.fn.countAll().as('count')).where('owner_did', '=', ownerDID).executeTakeFirst();
+        if (Number(row?.count ?? 0) >= maxKeyPackagesPerDID) {
+            throw new KeyPackageQuotaExceededError(`DID ${ownerDID} exceeds the maximum of ${maxKeyPackagesPerDID} stored key packages`);
+        }
+        await db.insertInto('hub_key_packages').values({
+            owner_did: ownerDID,
+            key_package: keyPackage,
+            not_after: notAfter ?? null
+        }).execute();
+    }
+    async function fetchKeyPackages({ ownerDID, count }) {
+        // Expired entries are DELETED first, not filtered after the limit: a run of dead rows would
+        // otherwise consume the whole page while live packages waited behind them.
+        await deleteExpiredKeyPackages(ownerDID);
+        // Atomic delete-returning: a select+delete pair would let two concurrent fetches return the
+        // same key package twice.
+        const rows = await db.deleteFrom('hub_key_packages').where('id', 'in', db.selectFrom('hub_key_packages').select('id').where('owner_did', '=', ownerDID).orderBy('id', 'asc').limit(count ?? 1)).returning('key_package').execute();
+        return rows.map((r)=>r.key_package);
+    }
+    async function countKeyPackages({ ownerDID }) {
+        const row = await db.selectFrom('hub_key_packages').select((eb)=>eb.fn.countAll().as('count')).where('owner_did', '=', ownerDID).where((eb)=>eb.or([
+                eb('not_after', 'is', null),
+                eb('not_after', '>', nowSeconds())
+            ])).executeTakeFirst();
+        return Number(row?.count ?? 0);
+    }
+    async function storeLastResortKeyPackage({ ownerDID, keyPackage }) {
+        await db.insertInto('hub_last_resort_key_packages').values({
+            owner_did: ownerDID,
+            key_package: keyPackage
+        }).onConflict((oc)=>{
+            return oc.column('owner_did').doUpdateSet({
+                key_package: (eb)=>eb.ref('excluded.key_package')
+            });
+        }).execute();
+    }
+    async function fetchLastResortKeyPackage({ ownerDID }) {
+        // Never consumes: the package carries MLS's `last_resort` extension, so serving it twice is
+        // the availability floor rather than the init-key reuse `fetchKeyPackages` prevents.
+        const row = await db.selectFrom('hub_last_resort_key_packages').select('key_package').where('owner_did', '=', ownerDID).executeTakeFirst();
+        return row?.key_package ?? null;
+    }
+    async function subscribe(subscribeParams) {
+        const { subscriberDID, topicID } = subscribeParams;
+        // Refused, never clamped: a peer that believed it had asked for more would be stranded.
+        if (subscribeParams.retention != null && maxRetention != null && subscribeParams.retention > maxRetention) {
+            throw new RetentionExceededError(`requested retention ${subscribeParams.retention} exceeds the hub maximum ${maxRetention}`);
+        }
+        const retention = subscribeParams.retention ?? defaultRetention;
+        // Charged on NEW rows only: refusing a refresh would strand a subscriber at the cap on every
+        // reconnect.
+        const held = await db.selectFrom('hub_subscriptions').select('topic_id').where('subscriber_did', '=', subscriberDID).execute();
+        if (!held.some((row)=>row.topic_id === topicID) && held.length >= maxSubscriptionsPerDID) {
+            throw new SubscriptionQuotaExceededError(`DID ${subscriberDID} exceeds the maximum of ${maxSubscriptionsPerDID} subscriptions`);
+        }
+        // Upsert, so re-subscribing refreshes the activity timestamp and retention rather than failing
+        // or duplicating.
+        await db.insertInto('hub_subscriptions').values({
+            topic_id: topicID,
+            subscriber_did: subscriberDID,
+            last_active_at: Date.now(),
+            retention
+        }).onConflict((oc)=>{
+            return oc.columns([
+                'topic_id',
+                'subscriber_did'
+            ]).doUpdateSet({
+                last_active_at: (eb)=>eb.ref('excluded.last_active_at'),
+                retention: (eb)=>eb.ref('excluded.retention')
+            });
+        }).execute();
+    }
+    async function unsubscribe({ subscriberDID, topicID }) {
+        await db.deleteFrom('hub_subscriptions').where('topic_id', '=', topicID).where('subscriber_did', '=', subscriberDID).execute();
+        // A delivery operation, not a trim: drop this subscriber's pending deliveries for the topic and
+        // GC any MAILBOX frame left without a recipient. Log frames and the head are never touched.
+        const pending = await db.selectFrom('hub_deliveries').innerJoin('hub_messages', 'hub_messages.sequence_id', 'hub_deliveries.sequence_id').select('hub_deliveries.sequence_id').where('hub_deliveries.recipient_did', '=', subscriberDID).where('hub_messages.topic_id', '=', topicID).execute();
+        if (pending.length === 0) return;
+        const sequenceIDs = pending.map((r)=>r.sequence_id);
+        await db.deleteFrom('hub_deliveries').where('recipient_did', '=', subscriberDID).where('sequence_id', 'in', sequenceIDs).execute();
+        const remaining = await db.selectFrom('hub_deliveries').select('sequence_id').where('sequence_id', 'in', sequenceIDs).execute();
+        const stillDelivered = new Set(remaining.map((r)=>r.sequence_id));
+        const orphaned = sequenceIDs.filter((id)=>!stillDelivered.has(id));
+        if (orphaned.length > 0) {
+            await db.deleteFrom('hub_messages').where('sequence_id', 'in', orphaned).where('retain', '=', 'mailbox').execute();
+        }
+    }
+    async function getSubscribers({ topicID }) {
+        const rows = await db.selectFrom('hub_subscriptions').select('subscriber_did').where('topic_id', '=', topicID).execute();
+        return rows.map((r)=>r.subscriber_did);
+    }
+    return {
+        events,
+        publish,
+        fetch,
+        fetchTopic,
+        ack,
+        purge,
+        trim,
+        storeKeyPackage,
+        fetchKeyPackages,
+        countKeyPackages,
+        storeLastResortKeyPackage,
+        fetchLastResortKeyPackage,
+        subscribe,
+        unsubscribe,
+        getSubscribers
+    };
+}

package/lib/tables.d.ts

@@ -0,0 +1,46 @@
+import type { ColumnType } from '@hozon/db';
+export type HubTables = {
+    hub_messages: {
+        sequence_id: string;
+        sender_did: string;
+        topic_id: string;
+        payload: Uint8Array;
+        stored_at: number;
+        retain: string;
+    };
+    hub_deliveries: {
+        sequence_id: string;
+        recipient_did: string;
+    };
+    hub_key_packages: {
+        id: ColumnType<number, number | undefined, never>;
+        owner_did: string;
+        key_package: string;
+        not_after: ColumnType<number | null, number | null | undefined, never>;
+    };
+    hub_last_resort_key_packages: {
+        owner_did: string;
+        key_package: string;
+    };
+    hub_subscriptions: {
+        topic_id: string;
+        subscriber_did: string;
+        last_active_at: number;
+        retention: ColumnType<number, number | undefined, number>;
+    };
+    hub_topics: {
+        topic_id: string;
+        head: string;
+        removed_through: ColumnType<string | null, string | null | undefined, string | null>;
+    };
+    hub_sequence: {
+        id: number;
+        counter: number;
+    };
+    hub_publish_ids: {
+        topic_id: string;
+        publish_id: string;
+        sequence_id: string | null;
+        recorded_at: number;
+    };
+};

package/lib/tables.js

@@ -0,0 +1 @@
+export { };

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@kumiai/hub-store",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.10.0",
+  "description": "SQL hub store for Kumiai hubs, backed by Hozon",
+  "keywords": [
+    "hub",
+    "store",
+    "sql",
+    "hozon"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TairuFramework/kumiai",
+    "directory": "packages/hub-store"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib/*"
+  ],
+  "dependencies": {
+    "@hozon/adapter": "^0.1.0",
+    "@hozon/db": "^0.2.2",
+    "@kumiai/hub-protocol": "^0.10.1",
+    "@sozai/event": "^0.1.5"
+  },
+  "devDependencies": {
+    "@enkaku/client": "^0.21.3",
+    "@enkaku/protocol": "^0.21.4",
+    "@enkaku/transport": "^0.21.3",
+    "@hozon/node-sqlite": "^0.1.0",
+    "@hozon/postgres": "^0.1.0",
+    "@kokuin/token": "^0.5.0",
+    "@kumiai/hub-conformance": "^0.10.1",
+    "@kumiai/hub-server": "^0.10.2",
+    "@testcontainers/postgresql": "^12.1.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "build:clean": "del lib",
+    "build:js": "del 'lib/**/*.js' && swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
+    "build:types": "del 'lib/**/*.d.ts' 'lib/**/*.d.ts.map' && tsc --emitDeclarationOnly --skipLibCheck",
+    "test": "pnpm run test:types && pnpm run test:unit",
+    "test:types": "tsc --noEmit --skipLibCheck -p tsconfig.test.json",
+    "test:unit": "vitest run"
+  }
 }