@zhin.js/harness 0.0.0-stage → 1.0.1

package/lib/mailbox.d.ts

@@ -0,0 +1,6 @@
+import type { Mailbox, MailboxOptions } from './contracts.js';
+export interface MailboxLocalOptions {
+    /** Receives swallowed errors from `onTurnFinished` and policy callbacks / invalid batch selections. */
+    readonly onError?: (error: unknown, context: string) => void;
+}
+export declare function createMailbox(options: MailboxOptions, local?: MailboxLocalOptions): Mailbox;

package/lib/mailbox.js

@@ -0,0 +1,422 @@
+/**
+ * Mailbox scheduler (ADR 0048 §3.1, H3).
+ *
+ * Semantics:
+ * - Key = (mail.to, laneOf(mail)). A lane defaults to the mail's engagement,
+ *   so without explicit lanes one actor runs one turn per engagement at a
+ *   time. At most one turn runs per key; different keys run in parallel,
+ *   bounded by `maxConcurrentTurns` across all keys.
+ * - Fairness: when a slot frees, idle keys are offered the slot in global
+ *   arrival order of their oldest queued mail, so a busy key cannot starve
+ *   the others. A key whose policy says `wait` does not hold a slot.
+ * - Policy (`InboxPolicy`, all members optional): `onPost` decides what a new
+ *   mail does (enqueue / supersede / stop / reject), `ready` picks the next
+ *   batch of an idle key or asks to wait until a time (merge and danmaku
+ *   windows), `staleOf` answers the running turn's pre-send check. Without a
+ *   policy the mailbox is plain FIFO, one mail per turn.
+ * - A `ready` batch must be an in-order subsequence of the key's queue that
+ *   contains its first mail; anything else is a programming error and only
+ *   the first mail runs. Selected mails leave the queue.
+ * - Supersede and stale discard requeue the running batch (in front of the
+ *   queue / right before the follow-up's group). Requeued mails are reported
+ *   to `onTurnFinished` only once, by the turn that finally answers them.
+ * - Queued mails older than `queueTtlMs` when their key would start are
+ *   dropped (`expired`). Dropped and cancelled mails are reported one by one
+ *   with `{status:'cancelled', reason}`.
+ * - `post` never starts a turn synchronously; turns start in a microtask (or
+ *   when a `wait` timer fires, via the injectable `setTimer`).
+ * - A runner rejection becomes `{status:'failed', content: message}`.
+ *   `onTurnFinished` is awaited before the key (and its slot) is released;
+ *   errors it throws are swallowed and reported through `onError`.
+ * - `cancel` aborts a running batch's signal (a runner that resolves with a
+ *   non-cancelled status after abort is reported as cancelled), or removes a
+ *   queued mail and reports it cancelled.
+ * - `close` rejects new posts, drops queued mails (reported cancelled), aborts
+ *   running turns, clears wait timers and resolves once everything settled.
+ */
+import { laneOf, senderOf } from './contracts.js';
+const FRESH = Object.freeze({ kind: 'fresh' });
+function defaultSetTimer(callback, delayMs) {
+    const handle = setTimeout(callback, delayMs);
+    handle.unref?.();
+    return () => clearTimeout(handle);
+}
+export function createMailbox(options, local = {}) {
+    const policy = options.policy ?? {};
+    const now = options.now ?? Date.now;
+    const setTimer = options.setTimer ?? defaultSetTimer;
+    const ttl = Math.max(0, options.queueTtlMs ?? 0);
+    const keys = new Map();
+    const lastTurns = new Map();
+    const settling = new Set();
+    const idleWaiters = [];
+    let seq = 0;
+    let runningCount = 0;
+    let queuedCount = 0;
+    let notifying = 0;
+    let closed = false;
+    let pumpScheduled = false;
+    const report = (error, context) => {
+        try {
+            local.onError?.(error, context);
+        }
+        catch {
+            /* ignore */
+        }
+    };
+    const keyId = (actor, lane) => `${actor}\u0000${lane}`;
+    const keyOf = (st, first) => ({
+        actor: st.actor,
+        lane: st.lane,
+        engagementId: (first ?? st.pending[0]?.mail ?? st.running?.batch[0]?.mail)?.engagementId ?? st.lastEngagement,
+    });
+    const runningView = (r) => ({
+        batch: r.batch,
+        startedAt: r.startedAt,
+        startSeq: r.startSeq,
+        delivered: r.delivered,
+        acted: r.acted,
+    });
+    const viewOf = (st) => {
+        const last = lastTurns.get(keyId(st.actor, st.lane));
+        return {
+            key: keyOf(st),
+            now: now(),
+            pending: st.pending.slice(),
+            ...(st.running ? { running: runningView(st.running) } : {}),
+            ...(last ? { lastTurn: last } : {}),
+        };
+    };
+    const checkIdle = () => {
+        if (runningCount === 0 && queuedCount === 0 && notifying === 0) {
+            for (const w of idleWaiters.splice(0))
+                w();
+        }
+    };
+    const notify = async (key, batch, result) => {
+        try {
+            await options.onTurnFinished?.(key, batch, result);
+        }
+        catch (e) {
+            report(e, 'onTurnFinished');
+        }
+    };
+    const notifyDetached = (key, batch, result) => {
+        notifying++;
+        const p = notify(key, batch, result).finally(() => {
+            notifying--;
+            settling.delete(p);
+            checkIdle();
+        });
+        settling.add(p);
+    };
+    /** Removes `entries` from the queue and reports each one cancelled. */
+    const drop = (st, entries, reason, content) => {
+        if (entries.length === 0)
+            return;
+        const gone = new Set(entries);
+        st.pending = st.pending.filter((e) => !gone.has(e));
+        queuedCount -= entries.length;
+        for (const e of entries) {
+            notifyDetached(keyOf(st, e.mail), [e.mail], { status: 'cancelled', reason, ...(content !== undefined ? { content } : {}) });
+        }
+    };
+    const clearTimer = (st) => {
+        st.cancelTimer?.();
+        st.cancelTimer = undefined;
+    };
+    const cleanup = (st) => {
+        if (st.pending.length === 0 && !st.running) {
+            clearTimer(st);
+            const id = keyId(st.actor, st.lane);
+            if (keys.get(id) === st)
+                keys.delete(id);
+        }
+    };
+    const schedulePump = () => {
+        if (pumpScheduled)
+            return;
+        pumpScheduled = true;
+        queueMicrotask(() => {
+            pumpScheduled = false;
+            pump();
+        });
+    };
+    const pruneMemory = (t) => {
+        const memory = Math.max(0, policy.memoryMs ?? 0);
+        for (const [id, last] of lastTurns) {
+            if (t - last.endedAt >= memory && !keys.get(id)?.running)
+                lastTurns.delete(id);
+        }
+    };
+    const decideReady = (st) => {
+        const fallback = { kind: 'run', batch: [st.pending[0].mail] };
+        if (!policy.ready)
+            return fallback;
+        let decision;
+        try {
+            decision = policy.ready(viewOf(st));
+        }
+        catch (e) {
+            report(e, 'batch');
+            return fallback;
+        }
+        if (decision.kind === 'wait')
+            return decision;
+        let cursor = 0;
+        const valid = decision.batch.length > 0 &&
+            decision.batch[0] === st.pending[0].mail &&
+            decision.batch.every((m) => {
+                while (cursor < st.pending.length && st.pending[cursor].mail !== m)
+                    cursor++;
+                if (cursor >= st.pending.length)
+                    return false;
+                cursor++;
+                return true;
+            });
+        if (!valid) {
+            report(new Error('invalid batch selection'), 'batch');
+            return fallback;
+        }
+        return decision;
+    };
+    const pump = () => {
+        if (closed)
+            return;
+        const t = now();
+        pruneMemory(t);
+        const idle = [...keys.values()].filter((st) => !st.running && st.pending.length > 0);
+        for (const st of idle) {
+            if (ttl > 0)
+                drop(st, st.pending.filter((e) => t - e.postedAt > ttl), 'expired', 'expired');
+        }
+        const candidates = idle
+            .filter((st) => {
+            if (st.pending.length > 0)
+                return true;
+            cleanup(st);
+            return false;
+        })
+            .sort((a, b) => a.pending[0].seq - b.pending[0].seq);
+        for (const st of candidates) {
+            if (runningCount >= options.maxConcurrentTurns)
+                return;
+            const decision = decideReady(st);
+            if (decision.kind === 'run') {
+                start(st, decision.batch);
+                continue;
+            }
+            clearTimer(st);
+            if (decision.until !== undefined) {
+                st.cancelTimer = setTimer(() => {
+                    st.cancelTimer = undefined;
+                    schedulePump();
+                }, Math.max(0, decision.until - t));
+            }
+        }
+    };
+    const staleCheck = (st, running) => {
+        if (running.discarded)
+            return running.discarded;
+        if (st.running !== running || !policy.staleOf)
+            return FRESH;
+        let decision;
+        try {
+            decision = policy.staleOf({ ...viewOf(st), running: runningView(running) });
+        }
+        catch (e) {
+            report(e, 'staleOf');
+            return FRESH;
+        }
+        if (decision.kind !== 'discard')
+            return decision;
+        const anchor = st.pending.findIndex((e) => e.mail.id === decision.carryInto);
+        if (anchor < 0) {
+            report(new Error(`stale carry target ${decision.carryInto} is not queued`), 'staleOf');
+            return FRESH;
+        }
+        const t = now();
+        const carried = running.batch
+            .filter((e) => !running.requeued.has(e.mail.id))
+            .map((e) => ({ mail: e.mail, seq: e.seq, postedAt: t, carriedInto: decision.carryInto }));
+        st.pending.splice(anchor, 0, ...carried);
+        queuedCount += carried.length;
+        for (const e of carried)
+            running.requeued.add(e.mail.id);
+        running.discarded = Object.freeze({ kind: 'discard', senders: Object.freeze([...decision.senders]) });
+        return running.discarded;
+    };
+    const start = (st, selected) => {
+        clearTimer(st);
+        const chosen = new Set(selected);
+        const entries = st.pending.filter((e) => chosen.has(e.mail));
+        st.pending = st.pending.filter((e) => !chosen.has(e.mail));
+        queuedCount -= entries.length;
+        const t = now();
+        const running = {
+            batch: entries,
+            controller: new AbortController(),
+            startedAt: t,
+            startSeq: seq,
+            delivered: false,
+            acted: false,
+            requeued: new Set(),
+        };
+        const facts = Object.freeze({
+            queuedMs: Math.max(0, t - Math.min(...entries.map((e) => e.postedAt))),
+            mergedMessages: entries.length,
+            supersededPrevious: entries.some((e) => e.superseded === true),
+            carried: entries.some((e) => e.carriedInto !== undefined),
+            evicted: st.evicted,
+        });
+        st.evicted = 0;
+        st.running = running;
+        runningCount++;
+        const batch = entries.map((e) => e.mail);
+        const control = {
+            facts,
+            markDelivered: () => { running.delivered = true; },
+            markActed: () => { running.acted = true; },
+            staleCheck: () => staleCheck(st, running),
+        };
+        const p = (async () => {
+            let result;
+            try {
+                result = await options.run(st.actor, batch, running.controller.signal, control);
+            }
+            catch (e) {
+                result = { status: 'failed', content: e instanceof Error ? e.message : String(e) };
+            }
+            if (running.controller.signal.aborted && result.status !== 'cancelled') {
+                result = { status: 'cancelled', content: result.content };
+            }
+            lastTurns.set(keyId(st.actor, st.lane), { batch, endedAt: now() });
+            const answered = batch.filter((m) => !running.requeued.has(m.id));
+            if (answered.length > 0)
+                await notify(keyOf(st, answered[0]), answered, result);
+        })().finally(() => {
+            st.running = undefined;
+            runningCount--;
+            cleanup(st);
+            settling.delete(p);
+            if (!closed)
+                schedulePump();
+            checkIdle();
+        });
+        settling.add(p);
+    };
+    const decidePost = (st, entry) => {
+        if (!policy.onPost)
+            return { kind: 'enqueue' };
+        try {
+            return policy.onPost(entry, viewOf(st));
+        }
+        catch (e) {
+            report(e, 'onPost');
+            return { kind: 'enqueue' };
+        }
+    };
+    return {
+        post(mail) {
+            if (closed)
+                return { accepted: false, code: 'mailbox_closed', message: 'mailbox is closed' };
+            const lane = laneOf(mail);
+            const id = keyId(mail.to, lane);
+            const st = keys.get(id) ?? { actor: mail.to, lane, pending: [], evicted: 0, lastEngagement: mail.engagementId };
+            const entry = { mail, seq, postedAt: now() };
+            const decision = decidePost(st, entry);
+            if (decision.kind === 'reject')
+                return { accepted: false, code: decision.code, message: decision.message };
+            if (decision.kind === 'stop') {
+                st.running?.controller.abort('stopped');
+                const senders = new Set(decision.cancelSenders);
+                drop(st, st.pending.filter((e) => senders.has(senderOf(e.mail))), 'stopped', 'stopped');
+                cleanup(st);
+                checkIdle();
+                return { accepted: true, position: 0, disposition: 'stopped' };
+            }
+            const evict = decision.kind === 'enqueue' && decision.evict ? new Set(decision.evict) : undefined;
+            const evicted = evict ? st.pending.filter((e) => evict.has(e.mail.id)) : [];
+            if (st.pending.length - evicted.length >= options.maxQueuedPerKey) {
+                return { accepted: false, code: 'queue_full', message: `queue full for ${mail.to} in ${lane}` };
+            }
+            if (!keys.has(id))
+                keys.set(id, st);
+            st.lastEngagement = mail.engagementId;
+            seq++;
+            let position;
+            let disposition;
+            const running = st.running;
+            if (decision.kind === 'supersede' && running) {
+                running.controller.abort('superseded');
+                const t = entry.postedAt;
+                const requeued = running.batch
+                    .filter((e) => !running.requeued.has(e.mail.id))
+                    .map((e) => ({ mail: e.mail, seq: e.seq, postedAt: t, superseded: true }));
+                for (const e of requeued)
+                    running.requeued.add(e.mail.id);
+                const fresh = { ...entry, superseded: true };
+                st.pending.unshift(...requeued, fresh);
+                queuedCount += requeued.length + 1;
+                position = requeued.length + 1;
+                disposition = 'superseded';
+            }
+            else {
+                if (evicted.length > 0) {
+                    st.evicted += evicted.length;
+                    drop(st, evicted, 'evicted', 'evicted');
+                }
+                st.pending.push(entry);
+                queuedCount++;
+                position = st.pending.length;
+                disposition = decision.kind === 'enqueue' && decision.merged ? 'merged' : 'queued';
+            }
+            schedulePump();
+            return { accepted: true, position, disposition };
+        },
+        cancel(mailId, reason) {
+            for (const st of keys.values()) {
+                const i = st.pending.findIndex((e) => e.mail.id === mailId);
+                if (i >= 0) {
+                    drop(st, [st.pending[i]], 'cancelled', reason);
+                    cleanup(st);
+                    return true;
+                }
+                const running = st.running;
+                if (running && !running.requeued.has(mailId) && running.batch.some((e) => e.mail.id === mailId)) {
+                    running.controller.abort(reason ?? 'cancelled');
+                    return true;
+                }
+            }
+            return false;
+        },
+        cancelSender(key, senderId, reason = 'cancelled') {
+            const st = keys.get(keyId(key.actor, key.lane));
+            if (!st)
+                return 0;
+            const dropped = st.pending.filter((e) => senderOf(e.mail) === senderId);
+            drop(st, dropped, reason, reason);
+            cleanup(st);
+            return dropped.length;
+        },
+        idle() {
+            if (runningCount === 0 && queuedCount === 0 && notifying === 0)
+                return Promise.resolve();
+            return new Promise((resolve) => idleWaiters.push(resolve));
+        },
+        async close(reason) {
+            closed = true;
+            for (const st of [...keys.values()]) {
+                clearTimer(st);
+                drop(st, st.pending.slice(), 'closed', reason);
+                if (st.running)
+                    st.running.controller.abort(reason ?? 'closed');
+                else
+                    cleanup(st);
+            }
+            while (settling.size > 0)
+                await Promise.all([...settling]);
+            checkIdle();
+        },
+    };
+}

package/lib/policies/admission.d.ts

@@ -0,0 +1,48 @@
+/**
+ * IM admission as one inbox policy (ADR 0048 §3.1 / §8 H3): ports the
+ * semantics of `TurnAdmissionGate` (#725, ADR 0038 §1/§4/§5) onto the
+ * Mailbox. What happens to a mail that arrives on a lane:
+ *
+ * - **Not addressed** (`unaddressed`): an ordinary group message that
+ *   neither @s nor replies to the bot never becomes a turn
+ *   (`not_addressed`).
+ * - **Explicit stop** (`isStop`) from the running batch's initiator (or the
+ *   master) aborts the running turn and drops the stopping sender's and the
+ *   initiator's queued mails; the stop itself never runs. Anyone else:
+ *   `forbidden`; nothing running: `not_running`.
+ * - **Same sender, nothing delivered yet** (`supersedeSameSender`): a plain
+ *   single-sender turn is aborted and its mails are requeued in front with
+ *   the new one, so one fresh turn answers everything the user typed.
+ * - **Same sender, already queued**: plain text joins the queued group
+ *   (burst coalescing).
+ * - **Anyone else**: queued FIFO behind the running turn. A member never
+ *   aborts, or joins, another member's single turn.
+ * - **Merge window** (`merge`): mergeable plain text from different senders
+ *   waits in one group, answered once quiet / at `maxWaitMs`.
+ * - **Stale reply** (`staleOf`): when a sender of the running turn follows up
+ *   into a merge window before anything was delivered, the reply is
+ *   discarded and the turn's mails join the follow-up's window, unless the
+ *   turn acted or this chain was already discarded once (starvation guard).
+ * - **Danmaku window** (`live`): see `live.ts`.
+ *
+ * `maxQueuedTurns` bounds queued groups (a window counts once); opening one
+ * more is `queue_full`. Queue TTL and the hard per-lane mail cap are
+ * `MailboxOptions.queueTtlMs` / `maxQueuedPerKey`.
+ */
+import type { InboxPolicy } from '../contracts.js';
+import { type LiveWindowOptions } from './live.js';
+import { type MergeWindowOptions } from './merge.js';
+export declare const DEFAULT_MAX_QUEUED_TURNS = 5;
+export interface InboxPolicyOptions {
+    /** Queued (not yet running) groups allowed per lane. */
+    readonly maxQueuedTurns: number;
+    /** When true, a new mail from the running turn's sender replaces that turn. */
+    readonly supersedeSameSender: boolean;
+    /** ADR 0038 §1 merge window; omitted = disabled. */
+    readonly merge?: MergeWindowOptions;
+    /** ADR 0038 §5 danmaku window; omitted = disabled. */
+    readonly live?: LiveWindowOptions;
+    /** Cap of one danmaku window. Default `LIVE_WINDOW_MAX_MESSAGES`. */
+    readonly liveMaxMessages?: number;
+}
+export declare function createInboxPolicy(input: InboxPolicyOptions): InboxPolicy;

package/lib/policies/admission.js

@@ -0,0 +1,118 @@
+import { classifyMail, groupInbox } from './groups.js';
+import { LIVE_WINDOW_MAX_MESSAGES, liveEvictions, liveWindowDueAt, normalizeLiveWindow } from './live.js';
+import { inboxMarkers } from './markers.js';
+import { mergeWindowDueAt, normalizeMergeWindow } from './merge.js';
+export const DEFAULT_MAX_QUEUED_TURNS = 5;
+const FRESH = Object.freeze({ kind: 'fresh' });
+export function createInboxPolicy(input) {
+    const merge = input.merge ? normalizeMergeWindow(input.merge) : undefined;
+    const live = input.live ? normalizeLiveWindow(input.live) : undefined;
+    const maxQueuedTurns = Math.max(0, Math.floor(input.maxQueuedTurns));
+    const liveMax = Math.max(1, Math.floor(input.liveMaxMessages ?? LIVE_WINDOW_MAX_MESSAGES));
+    const grouping = {
+        ...(merge ? { merge: { maxSenders: merge.maxSenders } } : {}),
+        live: live !== undefined,
+    };
+    const groups = (entries) => groupInbox(entries, grouping);
+    const runningKind = (running) => {
+        const all = groups(running.batch);
+        return all.length === 1 ? all[0].kind : 'merge';
+    };
+    const initiatorOf = (running) => inboxMarkers(running.batch[0].mail).senderId;
+    const supersedes = (senderId, plainText, view) => {
+        const running = view.running;
+        if (!input.supersedeSameSender || !running || running.delivered || !plainText)
+            return false;
+        if (runningKind(running) !== 'single')
+            return false;
+        const marks = running.batch.map((e) => inboxMarkers(e.mail));
+        if (!marks.every((m) => m.senderId === senderId && m.plainText))
+            return false;
+        return !view.pending.some((e) => inboxMarkers(e.mail).senderId === senderId);
+    };
+    const lastLiveEndedAt = (view) => {
+        const last = view.lastTurn;
+        if (!live || !last || last.batch.length === 0)
+            return undefined;
+        return classifyMail(last.batch[0], grouping) === 'live' ? last.endedAt : undefined;
+    };
+    return Object.freeze({
+        memoryMs: live?.minIntervalMs ?? 0,
+        onPost(entry, view) {
+            const m = inboxMarkers(entry.mail);
+            if (m.unaddressed && !m.isStop) {
+                return { kind: 'reject', code: 'not_addressed', message: 'the message does not address the agent' };
+            }
+            if (m.isStop) {
+                const running = view.running;
+                if (!running)
+                    return { kind: 'reject', code: 'not_running', message: 'nothing is running on this lane' };
+                const initiator = initiatorOf(running);
+                if (initiator !== m.senderId && !m.isMaster) {
+                    return { kind: 'reject', code: 'forbidden', message: 'only the turn initiator or the master may stop it' };
+                }
+                return { kind: 'stop', cancelSenders: [...new Set([m.senderId, initiator])] };
+            }
+            const before = groups(view.pending);
+            const after = groups([...view.pending, entry]);
+            const group = after.find((g) => g.entries.includes(entry));
+            if (group.entries.length > 1) {
+                if (group.kind === 'live') {
+                    const evict = liveEvictions(group.entries, liveMax);
+                    return evict.length > 0 ? { kind: 'enqueue', merged: true, evict } : { kind: 'enqueue', merged: true };
+                }
+                return { kind: 'enqueue', merged: true };
+            }
+            if (group.kind === 'single' && supersedes(m.senderId, m.plainText, view))
+                return { kind: 'supersede' };
+            if (before.length >= maxQueuedTurns) {
+                return { kind: 'reject', code: 'queue_full', message: `at most ${maxQueuedTurns} queued turns per lane` };
+            }
+            return { kind: 'enqueue' };
+        },
+        ready(view) {
+            const head = groups(view.pending)[0];
+            if (!head)
+                return { kind: 'wait' };
+            const batch = head.entries.map((e) => e.mail);
+            let due = view.now;
+            if (head.kind === 'merge' && merge)
+                due = mergeWindowDueAt(head, merge);
+            if (head.kind === 'live' && live)
+                due = liveWindowDueAt(head, lastLiveEndedAt(view), live);
+            return due <= view.now ? { kind: 'run', batch } : { kind: 'wait', until: due };
+        },
+        staleOf(view) {
+            if (!merge)
+                return FRESH;
+            const running = view.running;
+            const answered = new Set(running.batch.map((e) => inboxMarkers(e.mail).senderId));
+            const queued = groups(view.pending);
+            const stale = [];
+            for (const e of [...view.pending].sort((a, b) => a.seq - b.seq)) {
+                if (e.carriedInto !== undefined || e.seq < running.startSeq)
+                    continue;
+                if (classifyMail(e.mail, grouping) !== 'merge')
+                    continue;
+                const s = inboxMarkers(e.mail).senderId;
+                if (answered.has(s) && !stale.includes(s))
+                    stale.push(s);
+            }
+            if (stale.length === 0 || running.delivered)
+                return FRESH;
+            if (running.acted)
+                return { kind: 'send', senders: stale, reason: 'acted' };
+            if (running.batch.some((e) => e.carriedInto !== undefined))
+                return { kind: 'send', senders: stale, reason: 'starvation' };
+            let target;
+            for (let i = queued.length - 1; i >= 0 && !target; i -= 1) {
+                if (queued[i].kind === 'merge' && queued[i].senders.some((s) => stale.includes(s)))
+                    target = queued[i];
+            }
+            if (!target)
+                return FRESH;
+            const anchor = target.entries[0];
+            return { kind: 'discard', senders: stale, carryInto: anchor.carriedInto ?? anchor.mail.id };
+        },
+    });
+}

package/lib/policies/groups.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Turn groups of a lane's queue (ADR 0048 H3; semantics of the former
+ * `TurnAdmissionGate`, ADR 0038 §1/§5 and #725).
+ *
+ * The queue holds single mails; a group is the set of queued mails one turn
+ * will answer. Groups are recomputed from the queue on every decision, so
+ * the policy stays pure. Replaying the queue in order:
+ *
+ * - **live** (danmaku, when enabled): joins the lane's last live group, no
+ *   sender limit.
+ * - **merge** (mergeable plain text, when a merge window is enabled): joins
+ *   the last merge group that already has the sender (burst), else the last
+ *   merge group with fewer than `maxSenders` senders, else opens a new one.
+ * - **single** (everything else): joins the sender's own queued group when
+ *   that is a single plain-text group and this mail is plain text too
+ *   (burst coalescing); otherwise opens a new group. A member never joins
+ *   another member's single group.
+ * - Mails requeued by a stale discard (`carriedInto`) belong to the group of
+ *   their target mail, ahead of it, regardless of `maxSenders`; when the
+ *   target left the queue they form their own group.
+ *
+ * Groups are ordered by their first mail in the queue; the head group always
+ * contains the queue's first mail.
+ */
+import type { InboxEntry, Mail } from '../contracts.js';
+export type InboxGroupKind = 'single' | 'merge' | 'live';
+export interface InboxGroup {
+    readonly kind: InboxGroupKind;
+    /** In queue order. */
+    readonly entries: readonly InboxEntry[];
+    /** Distinct senders in queue order. */
+    readonly senders: readonly string[];
+    readonly plainText: boolean;
+    /** Earliest / latest (re)queue time of the group's own (not carried) mails. */
+    readonly openedAt: number;
+    readonly lastJoinedAt: number;
+}
+export interface InboxGroupingOptions {
+    /** Merge windows enabled; omitted = mergeable is ignored. */
+    readonly merge?: {
+        readonly maxSenders: number;
+    };
+    /** Danmaku windows enabled. */
+    readonly live?: boolean;
+}
+export declare function classifyMail(mail: Mail, options: InboxGroupingOptions): InboxGroupKind;
+export declare function groupInbox(entries: readonly InboxEntry[], options: InboxGroupingOptions): InboxGroup[];