@kumiai/hub-server 0.2.0 → 0.4.0

package/README.md

@@ -0,0 +1,84 @@
+# @kumiai/hub-server
+
+The hub server: `@kumiai/hub-protocol`'s procedure handlers wired to an `@enkaku` server, a live
+client registry for push fan-out, and an in-memory `HubStore` for development and tests.
+
+## Exports
+
+- `createHub({ transport, store, identity, ... })` — the whole server: handlers, registry, access
+  rules, rate limits, and an optional scheduled purge. Returns `{ registry, server }`.
+- `createHandlers({ registry, store, ... })` — the handlers alone, for a host assembling its own
+  server.
+- `createMemoryStore({ maxDepth?, retention? })` — an in-memory `HubStore`. For testing and
+  development; it is also what runs the `@kumiai/hub-conformance` suites in this repo.
+- `HubClientRegistry` — the live-connection table.
+- `createRateLimiter`, `DEFAULT_RATE_LIMITS`, `DEFAULT_KEYPACKAGE_FETCH_LIMITS`,
+  `DEFAULT_HUB_ACCESS_RULES`.
+
+```ts
+import { createHub, createMemoryStore } from '@kumiai/hub-server'
+
+const { server } = createHub({ transport, identity, store: createMemoryStore() })
+```
+
+## The hub is blind, and identity comes only from the signature
+
+Topic IDs are opaque and payloads are ciphertext the hub never opens. Every handler takes the caller
+DID from the **verified issuer** of the signed message, never from a wire field — so
+`hub/v1/topic/fetch` cannot be pointed at someone else's subscription, and a publish cannot claim
+another sender. The `identity` param is required for that reason.
+
+Authorization is two layers, and only the second one knows about topics: `accessRules` gate the
+procedures (the default lets any authenticated DID call them), and the optional
+`authorize(request)` hook decides publish and subscribe per topic. It takes one discriminated
+`AuthorizeRequest` — narrow on `request.action` — and returns `AuthorizeDecision`, either a boolean
+or `{ allow, reason?, code?, retryAfterMs? }`. `AuthorizeRequest` names six actions, but only
+`publish` and `subscribe` are dispatched today. The default allows any authenticated DID.
+
+## Durable subscription, ephemeral connection
+
+Subscription state lives in the store. `HubClientRegistry` holds only currently-connected clients and
+their live `hub/v1/receive` writers, so it routes push fan-out and nothing else — a restart loses no
+subscription.
+
+Binding a receive channel **evicts** whatever held the lane for that DID. A reconnect happens because
+the old connection broke and the server learns that last, so the stale writer must give way to the
+live one, not the other way round. The evicted channel is resolved rather than thrown: being replaced
+is not its error, and the client that replaced it is the same client.
+
+`hub/v1/receive` is always added to the server's `longLivedProcedures`, so open mailbox channels are
+exempt from `controllerTimeoutMs` and from the `maxConcurrentHandlers` cap. A host passing its own
+`limits` does not need to remember this.
+
+## What live fan-out does and does not push
+
+A **deduped** publish fans out to nobody. It appended nothing — the frame was already accepted and
+already delivered to whoever was subscribed then, and its sequenceID may since have been acked and
+its delivery row removed — so re-running the loop would push a frame every current subscriber has
+already applied, named by a dead sequenceID. Fan-out is for a genuine append only.
+
+The sender is excluded from its own fan-out. `hub/v1/topic/fetch` makes no such exclusion — a topic's
+log holds every log-class frame including the caller's own — so a reader that must not see its own
+messages twice filters them itself, as `@kumiai/rpc`'s drain does.
+
+A pushed frame carries `logPosition` **only** when it is log-class, and the key is spread in rather
+than assigned, because `logPosition: undefined` becomes a present key with a falsy value once it is
+off the wire — and the entire point of the field is that a reader can tell "no place in any log" from
+a place.
+
+## Retention: the store refuses, the hub schedules
+
+Two different knobs, easily confused. `createHub`'s `purge.olderThan` (default 7 days) is the **age
+bound** the scheduled sweep applies to a topic no subscriber asked to keep longer; the sweep runs on
+`purge.interval` (default 1 hour) and stops with the server. The **ceiling** on what a subscriber may
+request belongs to the store, because the store is what refuses the subscribe —
+`createMemoryStore`'s is 30 days, finite by design, since an unbounded ceiling lets any subscriber
+pin a topic's frames forever with `subscribe({ retention: 2 ** 31 })`. A subscribe above the ceiling
+is refused with `RetentionExceededError`, never clamped.
+
+`createMemoryStore`'s `maxDepth` (default 1000) evicts the oldest **log** frames beyond that count.
+Mailbox frames on the same topic are not counted, so a member cannot evict the log with a mailbox
+flood.
+
+Publish rate limits are per DID (20/s, burst 50) and per topic (100/s, burst 200), merged over
+`DEFAULT_RATE_LIMITS`; `hub/v1/keypackage/fetch` has its own request quota per requester DID.

package/lib/handlers.d.ts

@@ -2,8 +2,61 @@ import { type ProcedureHandlers } from '@enkaku/server';
 import type { HubProtocol, HubStore } from '@kumiai/hub-protocol';
 import { type RateLimitConfig } from './rateLimit.js';
 import type { HubClientRegistry } from './registry.js';
-export type AuthorizeAction = 'publish' | 'subscribe';
-export type AuthorizeHook = (did: string, action: AuthorizeAction, topicID: string) => boolean | Promise<boolean>;
+/**
+ * A single request to authorize. All six variants ship even though only `publish` and
+ * `subscribe` are currently enforced: the union is the exhaustive-switch surface a host's own
+ * `switch (req.action)` closes over, so adding a seventh variant later is the compatibility break
+ * this type exists to avoid.
+ *
+ * A host's `switch` need not handle every action today — an unrecognized action should default to
+ * allow, so a hook written before a new variant shipped doesn't silently start refusing a
+ * procedure that was previously ungated.
+ */
+export type AuthorizeRequest = {
+    action: 'publish';
+    did: string;
+    topicID: string;
+    retain: 'log' | 'mailbox';
+    payloadSize: number;
+} | {
+    action: 'subscribe';
+    did: string;
+    topicID: string;
+    retention?: number;
+} | {
+    action: 'unsubscribe';
+    did: string;
+    topicID: string;
+} | {
+    action: 'topic/fetch';
+    did: string;
+    topicID: string;
+} | {
+    action: 'keypackage/upload';
+    did: string;
+    count: number;
+} | {
+    action: 'keypackage/fetch';
+    did: string;
+    targetDID: string;
+    count: number;
+};
+/**
+ * A plain `boolean` is shorthand for `{ allow: boolean }`, with no reason, code, or retry hint.
+ *
+ * **`reason` is the only field a caller sees today.** `code` and `retryAfterMs` are reserved for
+ * enforcement that hasn't been built yet — a hook may return them, but both are silently dropped
+ * before the refusal reaches the client. They ship now because widening this union later is the
+ * break the surface exists to avoid; until enforcement lands, don't depend on either reaching a
+ * caller.
+ */
+export type AuthorizeDecision = boolean | {
+    allow: boolean;
+    reason?: string;
+    code?: string;
+    retryAfterMs?: number;
+};
+export type AuthorizeHook = (req: AuthorizeRequest) => AuthorizeDecision | Promise<AuthorizeDecision>;
 export type HubRateLimits = {
     perDID: RateLimitConfig;
     perTopic: RateLimitConfig;

package/lib/handlers.js

@@ -1,6 +1,12 @@
 import { HandlerError } from '@enkaku/server';
+import { hubErrorCodeOf } from '@kumiai/hub-protocol';
 import { fromB64, toB64 } from '@sozai/codec';
 import { createRateLimiter } from './rateLimit.js';
+function normalizeAuthorizeDecision(decision) {
+    return typeof decision === 'boolean' ? {
+        allow: decision
+    } : decision;
+}
 export const DEFAULT_RATE_LIMITS = {
     perDID: {
         rate: 20,
@@ -23,6 +29,20 @@ function getClientDID(ctx) {
     }
     return iss;
 }
+/**
+ * Re-raise a named store error with its wire code, so the caller can tell a lost compare-and-set
+ * from an unreachable hub. Anything else is not ours and passes through untouched.
+ */ function rethrowAsHandlerError(error) {
+    const code = hubErrorCodeOf(error);
+    if (code != null) {
+        throw new HandlerError({
+            code,
+            message: error instanceof Error ? error.message : code,
+            cause: error
+        });
+    }
+    throw error;
+}
 export function createHandlers(params) {
     const { store, registry } = params;
     const authorize = params.authorize ?? (()=>true);
@@ -66,13 +86,32 @@ export function createHandlers(params) {
         window.count++;
     }
     return {
-        'hub/publish': async (ctx)=>{
+        'hub/v1/publish': async (ctx)=>{
             const { topicID, payload } = ctx.param;
             const senderDID = getClientDID(ctx);
-            if (!await authorize(senderDID, 'publish', topicID)) {
+            // Decoded before authorize (not after) so the hook can see the real size. Two consequences
+            // are deliberate: an unauthorized caller sending malformed base64 gets a decode error instead
+            // of EK02, and decoding runs before both rate limiters, so oversized payloads are decoded
+            // before being throttled (bounded by the transport's own message limit). Deriving the size
+            // arithmetically from the base64 length instead was rejected — it drifts from
+            // `@sozai/codec`'s actual decoding and can hand the hook a wrong number.
+            //
+            // `retain` defaults to 'mailbox' here, matching the store's own default (`memoryStore.ts`) —
+            // the hook must never see an absent retain, since `AuthorizeRequest`'s `publish` variant
+            // declares it required.
+            const payloadBytes = fromB64(payload);
+            const retain = ctx.param.retain ?? 'mailbox';
+            const decision = normalizeAuthorizeDecision(await authorize({
+                action: 'publish',
+                did: senderDID,
+                topicID,
+                retain,
+                payloadSize: payloadBytes.length
+            }));
+            if (!decision.allow) {
                 throw new HandlerError({
                     code: 'EK02',
-                    message: 'Not authorized to publish to topic'
+                    message: decision.reason ?? 'Not authorized to publish to topic'
                 });
             }
             if (!didLimiter.tryConsume(senderDID)) {
@@ -87,45 +126,111 @@ export function createHandlers(params) {
                     message: 'Publish rate limit exceeded for topic'
                 });
             }
-            const payloadBytes = fromB64(payload);
-            const sequenceID = await store.publish({
-                senderDID,
-                topicID,
-                payload: payloadBytes
-            });
-            // Live-deliver to currently-connected subscribers (minus the sender).
-            const subscribers = await store.getSubscribers(topicID);
-            for (const recipientDID of subscribers){
-                if (recipientDID === senderDID) continue;
-                const client = registry.getClient(recipientDID);
-                if (client?.sendMessage != null) {
-                    client.sendMessage({
-                        sequenceID,
-                        senderDID,
-                        topicID,
-                        payload: payloadBytes
-                    });
+            let sequenceID;
+            let deduped;
+            try {
+                const result = await store.publish({
+                    senderDID,
+                    topicID,
+                    payload: payloadBytes,
+                    retain: ctx.param.retain,
+                    // Absent and null are different requests: null is the empty-topic sentinel, absent is
+                    // an unconditional publish. Spreading only when present keeps them apart.
+                    ...'expectedHead' in ctx.param ? {
+                        expectedHead: ctx.param.expectedHead
+                    } : {},
+                    publishID: ctx.param.publishID
+                });
+                sequenceID = result.sequenceID;
+                deduped = result.deduped;
+            } catch (error) {
+                rethrowAsHandlerError(error);
+            }
+            // A deduped publish appended nothing: already fanned out to whoever was subscribed then, and
+            // its sequenceID may since be acked and its delivery row gone. Re-running would push a frame
+            // every current subscriber already has, named by a dead sequenceID.
+            if (!deduped) {
+                // Only a log-class publish carries a logPosition. This sequenceID IS the log position (the
+                // store just minted it for this accepted append); a mailbox publish has none, since its
+                // recipient's own delivery-queue position isn't usable as a durable log cursor.
+                const logPosition = ctx.param.retain === 'log' ? {
+                    logPosition: sequenceID
+                } : {};
+                // Live-deliver to currently-connected subscribers (minus the sender).
+                const subscribers = await store.getSubscribers(topicID);
+                for (const recipientDID of subscribers){
+                    if (recipientDID === senderDID) continue;
+                    const client = registry.getClient(recipientDID);
+                    if (client?.sendMessage != null) {
+                        client.sendMessage({
+                            sequenceID,
+                            senderDID,
+                            topicID,
+                            payload: payloadBytes,
+                            ...logPosition
+                        });
+                    }
                 }
             }
             return {
                 sequenceID
             };
         },
-        'hub/subscribe': async (ctx)=>{
-            const { topicID } = ctx.param;
+        'hub/v1/subscribe': async (ctx)=>{
+            const { topicID, retention } = ctx.param;
             const clientDID = getClientDID(ctx);
-            if (!await authorize(clientDID, 'subscribe', topicID)) {
+            const decision = normalizeAuthorizeDecision(await authorize({
+                action: 'subscribe',
+                did: clientDID,
+                topicID,
+                retention
+            }));
+            if (!decision.allow) {
                 throw new HandlerError({
                     code: 'EK02',
-                    message: 'Not authorized to subscribe to topic'
+                    message: decision.reason ?? 'Not authorized to subscribe to topic'
+                });
+            }
+            try {
+                await store.subscribe({
+                    subscriberDID: clientDID,
+                    topicID,
+                    retention
                 });
+            } catch (error) {
+                rethrowAsHandlerError(error);
             }
-            await store.subscribe(clientDID, topicID);
             return {
                 subscribed: true
             };
         },
-        'hub/unsubscribe': async (ctx)=>{
+        'hub/v1/topic/fetch': async (ctx)=>{
+            const { topicID, after, limit } = ctx.param;
+            // subscriberDID is the authenticated caller (verified issuer), never a wire field — or any
+            // member could read another's topic log by naming them.
+            const subscriberDID = getClientDID(ctx);
+            try {
+                const result = await store.fetchTopic({
+                    subscriberDID,
+                    topicID,
+                    after,
+                    limit
+                });
+                return {
+                    messages: result.messages.map((message)=>({
+                            sequenceID: message.sequenceID,
+                            senderDID: message.senderDID,
+                            topicID: message.topicID,
+                            payload: toB64(message.payload)
+                        })),
+                    head: result.head,
+                    oldest: result.oldest
+                };
+            } catch (error) {
+                rethrowAsHandlerError(error);
+            }
+        },
+        'hub/v1/unsubscribe': async (ctx)=>{
             const { topicID } = ctx.param;
             const clientDID = getClientDID(ctx);
             await store.unsubscribe(clientDID, topicID);
@@ -133,27 +238,40 @@ export function createHandlers(params) {
                 unsubscribed: true
             };
         },
-        'hub/receive': async (ctx)=>{
+        'hub/v1/receive': async (ctx)=>{
             const clientDID = getClientDID(ctx);
             const { after } = ctx.param ?? {};
             registry.register(clientDID);
-            if (registry.isWriterBound(clientDID)) {
-                throw new HandlerError({
-                    code: 'EK01',
-                    message: `receive writer already bound for DID ${clientDID}`
-                });
-            }
             const writer = ctx.writable.getWriter();
             const reader = ctx.readable.getReader();
+            // Ends this channel when a newer one for the same DID takes the lane. Resolved, not thrown —
+            // replacement isn't this channel's error, and it's the same client that replaced it.
+            let endEvicted;
+            const evictedHere = new Promise((resolve)=>{
+                endEvicted = resolve;
+            });
+            let receiveToken;
             try {
-                registry.setReceiveWriter(clientDID, (message)=>{
+                // Binding evicts whatever held the lane: a reconnect means the old connection broke and the
+                // server learns last, so the stale writer must give way to the live one. See
+                // `HubClientRegistry.bindReceiveWriter`.
+                const { token, evicted } = registry.bindReceiveWriter(clientDID, (message)=>{
                     writer.write({
                         sequenceID: message.sequenceID,
                         senderDID: message.senderDID,
                         topicID: message.topicID,
-                        payload: toB64(message.payload)
+                        payload: toB64(message.payload),
+                        // Spread, not plain assignment — `logPosition: undefined` becomes a present key
+                        // once serialized, defeating the field's whole point (telling absent from present).
+                        ...message.logPosition != null ? {
+                            logPosition: message.logPosition
+                        } : {}
                     }).catch(()=>{});
-                });
+                }, ()=>endEvicted?.());
+                receiveToken = token;
+                // After the bind, so the lane is never unheld between the two — a frame arriving in that
+                // gap would have nowhere to go, and mailbox frames drop when nobody's there.
+                evicted?.();
                 let cursor = after;
                 while(true){
                     const result = await store.fetch({
@@ -166,19 +284,23 @@ export function createHandlers(params) {
                             sequenceID: msg.sequenceID,
                             senderDID: msg.senderDID,
                             topicID: msg.topicID,
-                            payload: toB64(msg.payload)
+                            payload: toB64(msg.payload),
+                            ...msg.logPosition != null ? {
+                                logPosition: msg.logPosition
+                            } : {}
                         });
                     }
                     cursor = result.cursor;
                     if (!result.hasMore) break;
                 }
             } catch (error) {
-                registry.clearReceiveWriter(clientDID);
+                if (receiveToken != null) registry.releaseReceiveWriter(clientDID, receiveToken);
                 registry.unregisterIfIdle(clientDID);
                 reader.cancel().catch(()=>{});
                 writer.abort(error).catch(()=>{});
                 throw error;
             }
+            const token = receiveToken;
             void (async ()=>{
                 try {
                     while(true){
@@ -196,18 +318,23 @@ export function createHandlers(params) {
                 }
             })();
             return new Promise((resolve)=>{
-                ctx.signal.addEventListener('abort', ()=>{
-                    registry.clearReceiveWriter(clientDID);
+                const finish = ()=>{
+                    // Token-scoped, so an already-evicted channel can't unbind the one that replaced it.
+                    if (token != null) registry.releaseReceiveWriter(clientDID, token);
                     registry.unregisterIfIdle(clientDID);
                     reader.cancel().catch(()=>{});
                     writer.close().catch(()=>{});
                     resolve(undefined);
-                }, {
+                };
+                // Evicted by a newer channel: end this one; `finish` releases only its own token, which is
+                // no longer current.
+                void evictedHere.then(finish);
+                ctx.signal.addEventListener('abort', finish, {
                     once: true
                 });
             });
         },
-        'hub/keypackage/upload': async (ctx)=>{
+        'hub/v1/keypackage/upload': async (ctx)=>{
             const { keyPackages } = ctx.param;
             const clientDID = getClientDID(ctx);
             await Promise.all(keyPackages.map((kp)=>store.storeKeyPackage(clientDID, kp)));
@@ -215,7 +342,7 @@ export function createHandlers(params) {
                 stored: keyPackages.length
             };
         },
-        'hub/keypackage/fetch': async (ctx)=>{
+        'hub/v1/keypackage/fetch': async (ctx)=>{
             const requesterDID = getClientDID(ctx);
             assertKeyPackageFetchAllowed(requesterDID);
             const { did, count } = ctx.param;

package/lib/hub.d.ts

@@ -13,7 +13,11 @@ export declare const DEFAULT_HUB_ACCESS_RULES: AccessRules;
 export type HubPurgeOptions = {
     /** Interval between purge runs in milliseconds. Default: 3600000 (1 hour) */
     interval?: number;
-    /** Age in seconds after which unacked stored messages are purged. Default: 604800 (7 days) */
+    /**
+     * The hub's default retention in seconds: the age bound applied to a topic no subscriber asked
+     * to keep for longer. Default: 604800 (7 days). The maximum a subscriber may ask for is the
+     * store's, since the store is the thing that refuses the subscribe.
+     */
     olderThan?: number;
 };
 export type CreateHubParams = {
@@ -30,12 +34,15 @@ export type CreateHubParams = {
     authorize?: AuthorizeHook;
     /** Publish rate limits. Merged over {@link DEFAULT_RATE_LIMITS}. */
     rateLimits?: Partial<HubRateLimits>;
-    /** Quotas applied to hub/keypackage/fetch. Merged over {@link DEFAULT_KEYPACKAGE_FETCH_LIMITS}. */
+    /**
+     * Quotas applied to hub/v1/keypackage/fetch. Merged over
+     * {@link DEFAULT_KEYPACKAGE_FETCH_LIMITS}.
+     */
     keyPackageFetchLimits?: Partial<KeyPackageFetchLimits>;
     /** Scheduled purge of expired stored messages. Set to `false` to disable. */
     purge?: HubPurgeOptions | false;
     /**
-     * Server resource limits. `hub/receive` is always added to
+     * Server resource limits. `hub/v1/receive` is always added to
      * `longLivedProcedures` so open mailbox channels are exempt from
      * `controllerTimeoutMs` and from the `maxConcurrentHandlers` cap.
      */

package/lib/hub.js

@@ -25,7 +25,7 @@ export function createHub(params) {
         longLivedProcedures: [
             ...new Set([
                 ...params.limits?.longLivedProcedures ?? [],
-                'hub/receive'
+                'hub/v1/receive'
             ])
         ]
     };

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-export type { AuthorizeAction, AuthorizeHook, CreateHandlersParams, HubRateLimits, KeyPackageFetchLimits, } from './handlers.js';
+export type { AuthorizeDecision, AuthorizeHook, AuthorizeRequest, CreateHandlersParams, HubRateLimits, KeyPackageFetchLimits, } from './handlers.js';
 export { createHandlers, DEFAULT_KEYPACKAGE_FETCH_LIMITS, DEFAULT_RATE_LIMITS } from './handlers.js';
 export type { CreateHubParams, HubInstance, HubPurgeOptions } from './hub.js';
 export { createHub, DEFAULT_HUB_ACCESS_RULES } from './hub.js';

package/lib/memoryStore.d.ts

@@ -1,12 +1,34 @@
 import type { HubStore } from '@kumiai/hub-protocol';
+export type MemoryStoreRetention = {
+    /** Floor, in seconds, on how long a topic's frames are kept. Default 0. */
+    default?: number;
+    /**
+     * Ceiling, in seconds, on what a subscriber may request. Above it: RetentionExceededError.
+     * Default {@link DEFAULT_MAX_RETENTION} (30 days), finite by design — an unbounded ceiling lets
+     * any subscriber pin a topic's frames forever with `subscribe({ retention: 2**31 })`. A host
+     * wanting no ceiling sets `Number.POSITIVE_INFINITY` explicitly.
+     */
+    max?: number;
+};
 export type MemoryStoreOptions = {
-    /** Per-topic max retained messages; oldest are trimmed beyond this. Default 1000. */
+    /** Per-topic max retained entries; oldest are trimmed beyond this. Default 1000. */
     maxDepth?: number;
+    retention?: MemoryStoreRetention;
 };
 /**
- * In-memory implementation of HubStore for testing and development.
+ * In-memory HubStore for testing and development.
+ *
+ * Retention is a class (per publish) and a duration (per subscribe):
+ * - `'mailbox'` (default) is delivery-derived: readers are known at publish time, so the last ack
+ *   frees the frame, and a publish nobody is subscribed to is dropped outright.
+ * - `'log'` is not: a subscriber that must read a frame may not exist when it is published, so no
+ *   refcount over current subscribers can free it. It is appended whether or not anyone is
+ *   subscribed, and only `trim` or the age bound removes it.
+ *
+ * The store is told the class; it never infers it, and never reads a payload.
  *
- * Single message copy + per-subscriber delivery index + refcount GC. Recipients
- * are resolved from the subscription table at publish time, never passed in.
+ * Both classes are age-bounded: frames live for the longest retention any subscriber asked for,
+ * floored at the hub's default. For mailbox that bound sits alongside the ack GC, ack usually
+ * winning.
  */
 export declare function createMemoryStore(options?: MemoryStoreOptions): HubStore;

package/lib/memoryStore.js

@@ -1,138 +1,251 @@
+import { HeadMismatchError, NotSubscribedError, RetentionExceededError } from '@kumiai/hub-protocol';
 import { EventEmitter } from '@sozai/event';
 const DEFAULT_MAX_DEPTH = 1000;
+/** 30 days, in seconds. A finite default ceiling on requested retention. */ const DEFAULT_MAX_RETENTION = 2_592_000;
 function formatSequenceID(counter) {
     return String(counter).padStart(12, '0');
 }
 /**
- * In-memory implementation of HubStore for testing and development.
+ * The entry as a reader sees it, with the ONE piece of routing metadata a reader cannot recover for
+ * itself: where the frame sits in its topic's log.
  *
- * Single message copy + per-subscriber delivery index + refcount GC. Recipients
- * are resolved from the subscription table at publish time, never passed in.
+ * Present iff the entry is log-class, and the key is left off entirely otherwise — a mailbox frame
+ * has no place in a log, and a falsy placeholder is a position a reader's cursor would move to,
+ * skipping every log frame below it. This store mints one sequence for both, so the log position of
+ * a log-class frame IS its sequenceID here; a store that mints a separate per-recipient delivery
+ * sequence reports its log's own value, and the conformance suite pins the equality that matters —
+ * a pushed log frame's `logPosition` is the position `fetchTopic` serves that same frame at.
+ */ function asStoredMessage(entry) {
+    return {
+        sequenceID: entry.sequenceID,
+        senderDID: entry.senderDID,
+        topicID: entry.topicID,
+        payload: entry.payload,
+        ...entry.retain === 'log' ? {
+            logPosition: entry.sequenceID
+        } : {}
+    };
+}
+/**
+ * In-memory HubStore for testing and development.
+ *
+ * Retention is a class (per publish) and a duration (per subscribe):
+ * - `'mailbox'` (default) is delivery-derived: readers are known at publish time, so the last ack
+ *   frees the frame, and a publish nobody is subscribed to is dropped outright.
+ * - `'log'` is not: a subscriber that must read a frame may not exist when it is published, so no
+ *   refcount over current subscribers can free it. It is appended whether or not anyone is
+ *   subscribed, and only `trim` or the age bound removes it.
+ *
+ * The store is told the class; it never infers it, and never reads a payload.
+ *
+ * Both classes are age-bounded: frames live for the longest retention any subscriber asked for,
+ * floored at the hub's default. For mailbox that bound sits alongside the ack GC, ack usually
+ * winning.
  */ export function createMemoryStore(options = {}) {
     const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const defaultRetention = options.retention?.default ?? 0;
+    const maxRetention = options.retention?.max ?? DEFAULT_MAX_RETENTION;
     let counter = 0;
-    const messages = new Map();
+    const entries = new Map();
+    const topicLogs = new Map();
+    const heads = new Map();
     const deliveries = new Map();
-    const subscriptions = new Map();
-    const topicMessages = new Map();
+    /**
+   * publishID -> the sequenceID it was accepted as. Not a log entry and not reachable from one: no
+   * deleter takes a publishID, so `removeEntry`, `trim` and `purge` cannot touch this map even by
+   * mistake. Retained indefinitely — it is the only thing that lets a peer replaying its journal
+   * learn that a commit it never saw acknowledged had in fact landed.
+   */ const publishRecords = new Map();
+    /** Per topic: the subscribers, each with the retention it asked for. */ const subscriptions = new Map();
     const keyPackages = new Map();
     const events = new EventEmitter();
-    // Remove a message entirely: every recipient delivery list, the topic log,
-    // and the message record.
-    function deleteMessage(sequenceID) {
-        const record = messages.get(sequenceID);
-        if (record == null) return;
-        for (const recipient of record.recipients){
-            const list = deliveries.get(recipient);
+    // The age bound for a topic: the longest retention any of its subscribers asked for, floored
+    // by the hub's default and by the caller's own bound.
+    function retentionOf(topicID, floor) {
+        let retention = Math.max(floor, defaultRetention);
+        const subscribers = subscriptions.get(topicID);
+        if (subscribers != null) {
+            for (const requested of subscribers.values()){
+                if (requested > retention) retention = requested;
+            }
+        }
+        return retention;
+    }
+    // The only removal path for an entry. Pending deliveries of it go with it: they reference an
+    // entry that no longer exists, so they can no longer be pushed. `heads` is never touched — an
+    // empty log still has a head.
+    function removeEntry(sequenceID) {
+        const entry = entries.get(sequenceID);
+        if (entry == null) return;
+        for (const recipientDID of entry.pendingFor){
+            const list = deliveries.get(recipientDID);
             if (list != null) {
                 const index = list.indexOf(sequenceID);
                 if (index !== -1) list.splice(index, 1);
             }
         }
-        const topicLog = topicMessages.get(record.topicID);
-        if (topicLog != null) {
-            const index = topicLog.indexOf(sequenceID);
-            if (index !== -1) topicLog.splice(index, 1);
-            if (topicLog.length === 0) topicMessages.delete(record.topicID);
+        const log = topicLogs.get(entry.topicID);
+        if (log != null) {
+            const index = log.indexOf(sequenceID);
+            if (index !== -1) log.splice(index, 1);
+            if (log.length === 0) topicLogs.delete(entry.topicID);
         }
-        messages.delete(sequenceID);
+        entries.delete(sequenceID);
     }
-    // Drop one subscriber's delivery of a message; GC the message when its last
-    // recipient is gone (refcount → 0).
-    function removeDelivery(recipientDID, sequenceID) {
+    // Drop one recipient's pending delivery. A mailbox frame whose last delivery is gone has been
+    // read by everyone who was ever going to read it, so it goes with it. A log frame does not: the
+    // subscriber that needs it may not exist yet.
+    function dropDelivery(recipientDID, sequenceID) {
         const list = deliveries.get(recipientDID);
         if (list != null) {
             const index = list.indexOf(sequenceID);
             if (index !== -1) list.splice(index, 1);
         }
-        const record = messages.get(sequenceID);
-        if (record != null) {
-            record.recipients.delete(recipientDID);
-            if (record.recipients.size === 0) {
-                deleteMessage(sequenceID);
-            }
+        const entry = entries.get(sequenceID);
+        if (entry == null) return;
+        entry.pendingFor.delete(recipientDID);
+        if (entry.retain === 'mailbox' && entry.pendingFor.size === 0) {
+            removeEntry(sequenceID);
         }
     }
     return {
         events,
         async publish (params) {
+            const retain = params.retain ?? 'mailbox';
+            // The dedup check comes BEFORE the CAS; the order is load-bearing. A replay carries the
+            // already-accepted publishID and the journalled expectedHead, which the accepted publish
+            // itself made stale — comparing first would raise HeadMismatchError and tell the caller its
+            // commit was lost when it landed. The returned sequenceID may name an already-trimmed frame,
+            // which is correct: a replay asks "did my publish land?", not "give me my frame".
+            if (params.publishID != null) {
+                const accepted = publishRecords.get(params.publishID);
+                if (accepted !== undefined) {
+                    return {
+                        sequenceID: accepted,
+                        deduped: true
+                    };
+                }
+            }
+            // The CAS, before anything is minted or written. Head comparison, sequence mint, append and
+            // head advance are one indivisible step; a loser leaves log, head and sequence untouched (no
+            // entry, no delivery, no sequenceID consumed). Absent expectedHead this is skipped — the
+            // unconditional fast path every mailbox frame takes.
+            if (params.expectedHead !== undefined) {
+                const head = heads.get(params.topicID) ?? null;
+                if (head !== params.expectedHead) {
+                    throw new HeadMismatchError(`Publish to ${params.topicID} expected head ${params.expectedHead ?? 'null'}, but the head is ${head ?? 'null'}`);
+                }
+            }
             counter++;
             const sequenceID = formatSequenceID(counter);
-            // Recipients = current subscribers minus the sender. Zero recipients
-            // (no subscribers, or only the sender) → drop immediately, store nothing.
-            const subscribers = subscriptions.get(params.topicID);
+            if (params.publishID != null) {
+                publishRecords.set(params.publishID, sequenceID);
+            }
+            // Only a log publish moves the head. A head naming a mailbox frame is a head that the
+            // frame's own last ack deletes, leaving readers of the log a head they can never reach.
+            if (retain === 'log') {
+                heads.set(params.topicID, sequenceID);
+            }
+            // Recipients = current subscribers minus the sender.
             const recipients = new Set();
+            const subscribers = subscriptions.get(params.topicID);
             if (subscribers != null) {
-                for (const did of subscribers){
-                    if (did !== params.senderDID) recipients.add(did);
+                for (const subscriberDID of subscribers.keys()){
+                    if (subscriberDID !== params.senderDID) recipients.add(subscriberDID);
                 }
             }
-            if (recipients.size === 0) {
-                return sequenceID;
+            // A mailbox frame with no recipients has already been read by everyone who was going to
+            // read it. A log frame is kept regardless: its reader may not exist yet.
+            if (retain === 'mailbox' && recipients.size === 0) {
+                return {
+                    sequenceID,
+                    deduped: false
+                };
             }
-            const record = {
+            const entry = {
                 sequenceID,
                 senderDID: params.senderDID,
                 topicID: params.topicID,
                 payload: params.payload,
-                recipients,
-                storedAt: Date.now()
+                storedAt: Date.now(),
+                retain,
+                pendingFor: recipients
             };
-            messages.set(sequenceID, record);
-            for (const recipient of recipients){
-                let list = deliveries.get(recipient);
+            entries.set(sequenceID, entry);
+            let log = topicLogs.get(params.topicID);
+            if (log == null) {
+                log = [];
+                topicLogs.set(params.topicID, log);
+            }
+            log.push(sequenceID);
+            for (const recipientDID of recipients){
+                let list = deliveries.get(recipientDID);
                 if (list == null) {
                     list = [];
-                    deliveries.set(recipient, list);
+                    deliveries.set(recipientDID, list);
                 }
                 list.push(sequenceID);
             }
-            let topicLog = topicMessages.get(params.topicID);
-            if (topicLog == null) {
-                topicLog = [];
-                topicMessages.set(params.topicID, topicLog);
-            }
-            topicLog.push(sequenceID);
-            // Per-topic max-depth trim: drop oldest beyond the bound.
-            while(topicLog.length > maxDepth){
-                deleteMessage(topicLog[0]);
+            // Depth bound: a trim like any other (moves oldest, leaves head alone), counting LOG frames
+            // only. A mailbox frame is bounded by ack and age, not depth; counting it here would let any
+            // member evict the commit log with a mailbox flood. Only a log publish can push the log-class
+            // count over the bound, so this is skipped for the mailbox fast path.
+            if (retain === 'log') {
+                let logDepth = 0;
+                for (const id of log){
+                    if (entries.get(id)?.retain === 'log') logDepth++;
+                }
+                while(logDepth > maxDepth){
+                    const oldestLog = log.find((id)=>entries.get(id)?.retain === 'log');
+                    if (oldestLog == null) break;
+                    removeEntry(oldestLog);
+                    logDepth--;
+                }
             }
-            return sequenceID;
+            return {
+                sequenceID,
+                deduped: false
+            };
         },
         async fetch (params) {
             if (params.ack != null && params.ack.length > 0) {
                 for (const sequenceID of params.ack){
-                    removeDelivery(params.recipientDID, sequenceID);
+                    dropDelivery(params.recipientDID, sequenceID);
                 }
             }
-            const recipientDeliveries = deliveries.get(params.recipientDID);
-            if (recipientDeliveries == null || recipientDeliveries.length === 0) {
+            const pending = deliveries.get(params.recipientDID);
+            if (pending == null || pending.length === 0) {
                 return {
                     messages: [],
                     cursor: null
                 };
             }
-            let startIndex = 0;
-            if (params.after != null) {
-                const afterIndex = recipientDeliveries.indexOf(params.after);
-                if (afterIndex !== -1) {
-                    startIndex = afterIndex + 1;
+            // `after` is an exclusive cursor: the first pending delivery with sequenceID strictly greater
+            // than it. Pending is in append order (strictly increasing), so this is the position just
+            // past `after` whether or not `after` is still pending. Matching on the value (indexOf) would
+            // fall back to index 0 once the cursored delivery is acked or aged out between pages of a
+            // drain, silently restarting from the top and re-serving frames already handed out. Scanning
+            // for `> after` resumes where the cursor pointed even after its own entry is gone.
+            let startIndex = pending.length;
+            if (params.after == null) {
+                startIndex = 0;
+            } else {
+                for(let index = 0; index < pending.length; index++){
+                    if (pending[index] > params.after) {
+                        startIndex = index;
+                        break;
+                    }
                 }
             }
-            const available = recipientDeliveries.slice(startIndex);
+            const available = pending.slice(startIndex);
             const limit = params.limit ?? available.length;
             const selected = available.slice(0, limit);
             const hasMore = available.length > limit;
             const resultMessages = [];
             for (const sequenceID of selected){
-                const record = messages.get(sequenceID);
-                if (record != null) {
-                    resultMessages.push({
-                        sequenceID: record.sequenceID,
-                        senderDID: record.senderDID,
-                        topicID: record.topicID,
-                        payload: record.payload
-                    });
+                const entry = entries.get(sequenceID);
+                if (entry != null) {
+                    resultMessages.push(asStoredMessage(entry));
                 }
             }
             const cursor = resultMessages.length > 0 ? resultMessages[resultMessages.length - 1].sequenceID : null;
@@ -145,20 +258,68 @@ function formatSequenceID(counter) {
             }
             return result;
         },
+        async fetchTopic (params) {
+            if (!subscriptions.get(params.topicID)?.has(params.subscriberDID)) {
+                throw new NotSubscribedError(`${params.subscriberDID} is not a subscriber of ${params.topicID}`);
+            }
+            // A topic's LOG is its log-class frames and nothing else. A mailbox frame published to a log
+            // topic is still delivered (push is untouched) but never enters the log: it does not move the
+            // head, so a reader that saw one would hold a cursor naming a position the head can never
+            // reach, and every CAS anchored there would lose forever. Only the publisher's own `retain`
+            // sets the class.
+            const log = (topicLogs.get(params.topicID) ?? []).filter((sequenceID)=>entries.get(sequenceID)?.retain === 'log');
+            const after = params.after;
+            // Filter to the class BEFORE the limit: a page of mailbox frames must not eat the limit and
+            // hand back an empty page while log frames wait — a caller draining until a short page would
+            // stop early and strand itself.
+            const selected = after == null ? log : log.filter((sequenceID)=>sequenceID > after);
+            const limited = params.limit == null ? selected : selected.slice(0, params.limit);
+            const messages = [];
+            for (const sequenceID of limited){
+                const entry = entries.get(sequenceID);
+                if (entry != null) {
+                    messages.push(asStoredMessage(entry));
+                }
+            }
+            return {
+                messages,
+                head: heads.get(params.topicID) ?? null,
+                oldest: log.length > 0 ? log[0] : null
+            };
+        },
+        async trim (params) {
+            const log = topicLogs.get(params.topicID);
+            if (log == null) return;
+            for (const sequenceID of [
+                ...log
+            ]){
+                // Log-class frames only. A mailbox frame shares the topic's array but not its log: it is
+                // delivery-derived, freed by its last ack or by age, and trim never removes it — trimming
+                // the mixed array silently drops pending mail below the bound.
+                if (sequenceID < params.before && entries.get(sequenceID)?.retain === 'log') {
+                    removeEntry(sequenceID);
+                }
+            }
+        },
         async ack (params) {
             for (const sequenceID of params.sequenceIDs){
-                removeDelivery(params.recipientDID, sequenceID);
+                dropDelivery(params.recipientDID, sequenceID);
             }
         },
         async purge (params) {
-            const threshold = Date.now() - params.olderThan * 1000;
+            // The age bound, for both classes: the same removal path, the same invariants — head is
+            // untouched.
+            const now = Date.now();
             const purgedIDs = [];
-            for (const [sequenceID, record] of messages){
-                if (record.storedAt <= threshold) {
+            for (const [sequenceID, entry] of entries){
+                const retention = retentionOf(entry.topicID, params.olderThan);
+                if (entry.storedAt <= now - retention * 1000) {
                     purgedIDs.push(sequenceID);
-                    deleteMessage(sequenceID);
                 }
             }
+            for (const sequenceID of purgedIDs){
+                removeEntry(sequenceID);
+            }
             if (purgedIDs.length > 0) {
                 await events.emit('purge', {
                     sequenceIDs: purgedIDs
@@ -166,50 +327,43 @@ function formatSequenceID(counter) {
             }
             return purgedIDs;
         },
-        async subscribe (subscriberDID, topicID) {
-            let subs = subscriptions.get(topicID);
-            if (subs == null) {
-                subs = new Set();
-                subscriptions.set(topicID, subs);
+        async subscribe (params) {
+            const requested = params.retention ?? defaultRetention;
+            if (requested > maxRetention) {
+                throw new RetentionExceededError(`Requested retention of ${requested}s exceeds the maximum of ${maxRetention}s`);
+            }
+            let subscribers = subscriptions.get(params.topicID);
+            if (subscribers == null) {
+                subscribers = new Map();
+                subscriptions.set(params.topicID, subscribers);
             }
-            subs.add(subscriberDID);
+            subscribers.set(params.subscriberDID, requested);
         },
         async unsubscribe (subscriberDID, topicID) {
-            const subs = subscriptions.get(topicID);
-            if (subs != null) {
-                subs.delete(subscriberDID);
-                if (subs.size === 0) {
+            const subscribers = subscriptions.get(topicID);
+            if (subscribers != null) {
+                subscribers.delete(subscriberDID);
+                if (subscribers.size === 0) {
                     subscriptions.delete(topicID);
                 }
             }
-            // Drop this subscriber's pending deliveries for the topic.
-            const list = deliveries.get(subscriberDID);
-            if (list != null) {
+            // Drops this subscriber's pending deliveries for the topic — freeing a mailbox frame whose
+            // last delivery this was, and leaving a log frame standing.
+            const pending = deliveries.get(subscriberDID);
+            if (pending != null) {
                 for (const sequenceID of [
-                    ...list
+                    ...pending
                 ]){
-                    const record = messages.get(sequenceID);
-                    if (record != null && record.topicID === topicID) {
-                        removeDelivery(subscriberDID, sequenceID);
-                    }
-                }
-            }
-            // Last subscriber gone → drop the whole topic log immediately.
-            if (!subscriptions.has(topicID)) {
-                const topicLog = topicMessages.get(topicID);
-                if (topicLog != null) {
-                    for (const sequenceID of [
-                        ...topicLog
-                    ]){
-                        deleteMessage(sequenceID);
+                    if (entries.get(sequenceID)?.topicID === topicID) {
+                        dropDelivery(subscriberDID, sequenceID);
                     }
                 }
             }
         },
         async getSubscribers (topicID) {
-            const subs = subscriptions.get(topicID);
-            return subs == null ? [] : [
-                ...subs
+            const subscribers = subscriptions.get(topicID);
+            return subscribers == null ? [] : [
+                ...subscribers.keys()
             ];
         },
         async storeKeyPackage (ownerDID, keyPackage) {

package/lib/registry.d.ts

@@ -2,6 +2,10 @@ import type { StoredMessage } from '@kumiai/hub-protocol';
 export type ClientEntry = {
     did: string;
     sendMessage: ((message: StoredMessage) => void) | null;
+    /** Ends the currently bound receive channel. Set with the writer and cleared with it. */
+    endReceive: (() => void) | null;
+    /** Identifies the binding, so a channel can only ever release its OWN. */
+    token: symbol | null;
 };
 /**
  * Tracks online clients and their live receive-channel writers. Subscription
@@ -14,8 +18,33 @@ export declare class HubClientRegistry {
     unregister(did: string): void;
     /** Removes the entry only when no receive writer is bound. */
     unregisterIfIdle(did: string): void;
-    setReceiveWriter(did: string, writer: (message: StoredMessage) => void): void;
-    clearReceiveWriter(did: string): void;
+    /**
+     * Bind this DID's receive writer, EVICTING whatever was bound before it.
+     *
+     * One writer per DID, and the newest one wins. The alternative — refuse the second — reads as
+     * the safer rule and is not: a client whose socket died has a writer the server still believes
+     * in, because nothing has told it otherwise yet, and that belief outlives the socket by however
+     * long the transport takes to notice. Refusing on it means the reconnect that the client makes
+     * precisely BECAUSE its connection dropped is the one that gets turned away, and the member has
+     * no push lane until a timeout it cannot see or influence expires. Last-writer-wins costs a
+     * live connection only when the same authenticated DID opens a second channel, which is the
+     * same client and its own business.
+     *
+     * The eviction is handed back rather than run here: ending a channel is the handler's to do,
+     * and a registry that closed streams would be doing two jobs.
+     *
+     * The TOKEN is what keeps the eviction from unbinding its successor. The evicted handler runs
+     * its own cleanup afterwards — it does not know why it ended — and a `clear(did)` there would
+     * null the writer the new channel has just bound, leaving the DID online with nothing behind
+     * it. So a release names the binding it is releasing, and one that is no longer current is a
+     * no-op.
+     */
+    bindReceiveWriter(did: string, writer: (message: StoredMessage) => void, endReceive: () => void): {
+        token: symbol;
+        evicted: (() => void) | null;
+    };
+    /** Clear the binding this token names. A token that is no longer current is a no-op. */
+    releaseReceiveWriter(did: string, token: symbol): void;
     getClient(did: string): ClientEntry | undefined;
     isOnline(did: string): boolean;
     isWriterBound(did: string): boolean;

package/lib/registry.js

@@ -11,7 +11,9 @@
         }
         const entry = {
             did,
-            sendMessage: null
+            sendMessage: null,
+            endReceive: null,
+            token: null
         };
         this.#clients.set(did, entry);
         return entry;
@@ -25,19 +27,48 @@
             this.#clients.delete(did);
         }
     }
-    setReceiveWriter(did, writer) {
+    /**
+   * Bind this DID's receive writer, EVICTING whatever was bound before it.
+   *
+   * One writer per DID, and the newest one wins. The alternative — refuse the second — reads as
+   * the safer rule and is not: a client whose socket died has a writer the server still believes
+   * in, because nothing has told it otherwise yet, and that belief outlives the socket by however
+   * long the transport takes to notice. Refusing on it means the reconnect that the client makes
+   * precisely BECAUSE its connection dropped is the one that gets turned away, and the member has
+   * no push lane until a timeout it cannot see or influence expires. Last-writer-wins costs a
+   * live connection only when the same authenticated DID opens a second channel, which is the
+   * same client and its own business.
+   *
+   * The eviction is handed back rather than run here: ending a channel is the handler's to do,
+   * and a registry that closed streams would be doing two jobs.
+   *
+   * The TOKEN is what keeps the eviction from unbinding its successor. The evicted handler runs
+   * its own cleanup afterwards — it does not know why it ended — and a `clear(did)` there would
+   * null the writer the new channel has just bound, leaving the DID online with nothing behind
+   * it. So a release names the binding it is releasing, and one that is no longer current is a
+   * no-op.
+   */ bindReceiveWriter(did, writer, endReceive) {
         const entry = this.#clients.get(did);
-        if (entry == null) return;
-        if (entry.sendMessage != null) {
-            throw new Error(`receive writer already bound for DID ${did}`);
-        }
+        if (entry == null) return {
+            token: Symbol('unbound'),
+            evicted: null
+        };
+        const evicted = entry.endReceive;
+        const token = Symbol('receive');
         entry.sendMessage = writer;
+        entry.endReceive = endReceive;
+        entry.token = token;
+        return {
+            token,
+            evicted
+        };
     }
-    clearReceiveWriter(did) {
+    /** Clear the binding this token names. A token that is no longer current is a no-op. */ releaseReceiveWriter(did, token) {
         const entry = this.#clients.get(did);
-        if (entry != null) {
-            entry.sendMessage = null;
-        }
+        if (entry == null || entry.token !== token) return;
+        entry.sendMessage = null;
+        entry.endReceive = null;
+        entry.token = null;
     }
     getClient(did) {
         return this.#clients.get(did);

package/package.json

@@ -1,7 +1,6 @@
 {
   "name": "@kumiai/hub-server",
-  "version": "0.2.0",
-  "license": "MIT",
+  "version": "0.4.0",
   "description": "Hub server for Enkaku E2EE group message routing",
   "keywords": [
     "hub",
@@ -14,37 +13,37 @@
     "url": "https://github.com/TairuFramework/kumiai",
     "directory": "packages/hub-server"
   },
+  "license": "MIT",
+  "sideEffects": false,
   "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
   "exports": {
     ".": "./lib/index.js"
   },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
   "files": [
     "lib/*"
   ],
-  "sideEffects": false,
   "dependencies": {
-    "@sozai/codec": "^0.2.0",
-    "@sozai/event": "^0.1.1",
     "@enkaku/protocol": "^0.19.0",
     "@enkaku/server": "^0.19.0",
-    "@sozai/stream": "^0.2.0",
-    "@kokuin/token": "^0.2.0",
-    "@kumiai/mls": "^0.2.0",
-    "@kumiai/hub-protocol": "^0.1.0"
+    "@kokuin/token": "^0.3.0",
+    "@sozai/codec": "^0.2.0",
+    "@sozai/event": "^0.1.1",
+    "@kumiai/hub-protocol": "^0.4.0"
   },
   "devDependencies": {
     "@enkaku/client": "^0.19.0",
-    "@enkaku/transport": "^0.19.1"
+    "@enkaku/transport": "^0.19.1",
+    "@kumiai/hub-conformance": "^0.4.0"
   },
   "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
     "build:clean": "del lib",
     "build:js": "swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
     "build:types": "tsc --emitDeclarationOnly --skipLibCheck",
-    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "test": "pnpm run test:types && pnpm run test:unit",
     "test:types": "tsc --noEmit --skipLibCheck -p tsconfig.test.json",
-    "test:unit": "vitest run",
-    "test": "pnpm run test:types && pnpm run test:unit"
+    "test:unit": "vitest run"
   }
 }