@lloyal-labs/sdk 1.0.0

package/dist/BranchStore.d.ts

@@ -0,0 +1,125 @@
+import type { Branch } from './Branch';
+import type { SessionContext } from './types';
+/**
+ * High-throughput multi-branch decode operations
+ *
+ * The naive approach to N-branch generation is N sequential llama_decode()
+ * calls — each paying full GPU kernel launch overhead, memory barrier, and
+ * PCIe round-trip. BranchStore eliminates this by packing all branches into
+ * a single llama_batch and dispatching once: O(1) GPU round-trips regardless
+ * of branch count. The GPU parallelizes across sequences within the batch,
+ * so N branches approach the wall-time cost of 1.
+ *
+ * Two operations, two packing strategies:
+ *
+ * **commit()** — Generation step. Each branch contributes exactly 1 token.
+ * Packs N tokens into a single batch via `decode_each` (one row per sequence,
+ * all at their respective positions). Single `llama_decode()` call. Logits
+ * captured per-branch at batch index `i`. O(N) total work, O(1) GPU
+ * dispatches, O(1) amortized dispatch overhead per branch. Accept-first
+ * ordering with rollback: accepts each token into its branch's repeat-penalty
+ * window before decode, restores from clones if decode throws.
+ *
+ * **prefill()** — Bulk token injection. Each branch contributes a
+ * variable-length token array. Uses a two-pass bin-packing algorithm:
+ *
+ * - *Pass 1 (planning)*: Greedy first-fit packs items into chunks ≤ nBatch.
+ *   Items larger than nBatch get a dedicated chunk and fall through to
+ *   decode_many's internal auto-chunking (ceil(nTokens / nBatch) calls).
+ * - *Pass 2 (dispatch)*: Normal chunks dispatch via `decode_scatter` (one
+ *   `llama_decode` per chunk). Logits are indexed by flattened cursor
+ *   position: for item k in a chunk, logits live at `cursor + nTokens[k] - 1`.
+ *
+ * For T total tokens across N branches with batch capacity B:
+ * - Best case (T ≤ B): 1 GPU dispatch, all branches in one batch.
+ * - Worst case: ceil(T / B) dispatches. Each dispatch is fully packed.
+ * - Amortized per-token GPU overhead: O(1/B) — vanishes as batch fills.
+ *
+ * Does NOT accept tokens into the sampler penalty window — use for
+ * external/replayed tokens where repeat-penalty tracking is unwanted.
+ * For model-generated tokens, use {@link commit} instead.
+ *
+ * Both methods take `[branch, token(s)]` tuples — the branch-to-token
+ * binding is structural, not positional. After either call, each branch's
+ * logits snapshot is updated with the output distribution from its decoded
+ * token(s), ready for the next `produce()`/`sample()` call.
+ *
+ * @example 32-branch generation step — one GPU dispatch
+ * ```typescript
+ * const store = new BranchStore(ctx);
+ * const entries = await Promise.all(branches.map(async b => [b, (await b.produce()).token] as [Branch, number]));
+ * await store.commit(entries);  // 32 tokens, 1 llama_decode()
+ * ```
+ *
+ * @example Best-of-N with batched commit
+ * ```typescript
+ * const store = new BranchStore(ctx);
+ * const branches = [];
+ * for (const _ of [1, 2, 3]) branches.push(await root.fork());
+ *
+ * for (let step = 0; step < 50; step++) {
+ *   const produced = await Promise.all(branches.map(async b => [b, await b.produce()] as const));
+ *   const live = produced.filter(([, p]) => !p.isStop);
+ *   if (!live.length) break;
+ *   await store.commit(live.map(([b, p]) => [b, p.token]));
+ * }
+ * ```
+ *
+ * @example Asymmetric prefill — variable-length injections, auto-chunked
+ * ```typescript
+ * await store.prefill([
+ *   [branchA, systemPromptTokens],   // 200 tokens
+ *   [branchB, shortQueryTokens],     //  12 tokens
+ *   [branchC, longDocumentTokens],   // 800 tokens
+ * ]);
+ * // Bin-packed into ceil(1012 / nBatch) GPU dispatches
+ * ```
+ *
+ * @category Branching
+ */
+export declare class BranchStore {
+    private _ctx;
+    constructor(ctx: SessionContext);
+    /**
+     * Batched single-token commit for model-generated tokens
+     *
+     * Each tuple `[branch, token]` binds one token to one branch.
+     * Accepts each token into its branch's repeat-penalty window (for correct
+     * PPL measurement), then decodes all N tokens in a single llama_decode()
+     * call via decode_each and captures logits per-branch. Accept-first
+     * ordering with rollback: if decode throws, sampler/grammar/metrics are
+     * restored from clones taken before the accept.
+     *
+     * @param entries - Array of `[branch, token]` tuples (branches must not be disposed)
+     * @throws If any branch is disposed
+     */
+    commit(entries: [Branch, number][]): Promise<void>;
+    /**
+     * Batched variable-length prefill for external tokens
+     *
+     * Each tuple `[branch, tokens]` binds a token array to one branch.
+     * Each branch can receive a different number of tokens — decode_scatter
+     * handles variable-length runs and auto-chunks to fit nBatch.
+     *
+     * Does NOT call accept_token — use for external/replayed tokens where
+     * repeat-penalty tracking is unwanted. For model-generated tokens,
+     * use {@link commit} instead.
+     *
+     * @param entries - Array of `[branch, tokens]` tuples (branches must not be disposed)
+     * @throws If any branch is disposed
+     */
+    prefill(entries: [Branch, number[]][]): Promise<void>;
+    /**
+     * Retain only the winner branch — evict all other leases and free their slots.
+     *
+     * Nuclear operation: calls `kv::seq_keep` on the winner's seq_id (stripping all
+     * other sequences from KV cache in a single pass), then frees all loser slots
+     * and rebuilds the vacancy list. The winner's topology is reset (no parent, no children).
+     *
+     * @param winner - The branch to keep (must not be disposed, must hold a lease)
+     * @throws If winner is disposed or has no lease
+     */
+    retainOnly(winner: Branch): Promise<void>;
+    get available(): number;
+}
+//# sourceMappingURL=BranchStore.d.ts.map

package/dist/BranchStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BranchStore.d.ts","sourceRoot":"","sources":["../src/BranchStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,IAAI,CAAiB;gBAEjB,GAAG,EAAE,cAAc;IAI/B;;;;;;;;;;;;OAYG;IACG,MAAM,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAWxD;;;;;;;;;;;;;OAaG;IACG,OAAO,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAW3D;;;;;;;;;OASG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/C,IAAI,SAAS,IAAI,MAAM,CAEtB;CACF"}

package/dist/BranchStore.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BranchStore = void 0;
+/**
+ * High-throughput multi-branch decode operations
+ *
+ * The naive approach to N-branch generation is N sequential llama_decode()
+ * calls — each paying full GPU kernel launch overhead, memory barrier, and
+ * PCIe round-trip. BranchStore eliminates this by packing all branches into
+ * a single llama_batch and dispatching once: O(1) GPU round-trips regardless
+ * of branch count. The GPU parallelizes across sequences within the batch,
+ * so N branches approach the wall-time cost of 1.
+ *
+ * Two operations, two packing strategies:
+ *
+ * **commit()** — Generation step. Each branch contributes exactly 1 token.
+ * Packs N tokens into a single batch via `decode_each` (one row per sequence,
+ * all at their respective positions). Single `llama_decode()` call. Logits
+ * captured per-branch at batch index `i`. O(N) total work, O(1) GPU
+ * dispatches, O(1) amortized dispatch overhead per branch. Accept-first
+ * ordering with rollback: accepts each token into its branch's repeat-penalty
+ * window before decode, restores from clones if decode throws.
+ *
+ * **prefill()** — Bulk token injection. Each branch contributes a
+ * variable-length token array. Uses a two-pass bin-packing algorithm:
+ *
+ * - *Pass 1 (planning)*: Greedy first-fit packs items into chunks ≤ nBatch.
+ *   Items larger than nBatch get a dedicated chunk and fall through to
+ *   decode_many's internal auto-chunking (ceil(nTokens / nBatch) calls).
+ * - *Pass 2 (dispatch)*: Normal chunks dispatch via `decode_scatter` (one
+ *   `llama_decode` per chunk). Logits are indexed by flattened cursor
+ *   position: for item k in a chunk, logits live at `cursor + nTokens[k] - 1`.
+ *
+ * For T total tokens across N branches with batch capacity B:
+ * - Best case (T ≤ B): 1 GPU dispatch, all branches in one batch.
+ * - Worst case: ceil(T / B) dispatches. Each dispatch is fully packed.
+ * - Amortized per-token GPU overhead: O(1/B) — vanishes as batch fills.
+ *
+ * Does NOT accept tokens into the sampler penalty window — use for
+ * external/replayed tokens where repeat-penalty tracking is unwanted.
+ * For model-generated tokens, use {@link commit} instead.
+ *
+ * Both methods take `[branch, token(s)]` tuples — the branch-to-token
+ * binding is structural, not positional. After either call, each branch's
+ * logits snapshot is updated with the output distribution from its decoded
+ * token(s), ready for the next `produce()`/`sample()` call.
+ *
+ * @example 32-branch generation step — one GPU dispatch
+ * ```typescript
+ * const store = new BranchStore(ctx);
+ * const entries = await Promise.all(branches.map(async b => [b, (await b.produce()).token] as [Branch, number]));
+ * await store.commit(entries);  // 32 tokens, 1 llama_decode()
+ * ```
+ *
+ * @example Best-of-N with batched commit
+ * ```typescript
+ * const store = new BranchStore(ctx);
+ * const branches = [];
+ * for (const _ of [1, 2, 3]) branches.push(await root.fork());
+ *
+ * for (let step = 0; step < 50; step++) {
+ *   const produced = await Promise.all(branches.map(async b => [b, await b.produce()] as const));
+ *   const live = produced.filter(([, p]) => !p.isStop);
+ *   if (!live.length) break;
+ *   await store.commit(live.map(([b, p]) => [b, p.token]));
+ * }
+ * ```
+ *
+ * @example Asymmetric prefill — variable-length injections, auto-chunked
+ * ```typescript
+ * await store.prefill([
+ *   [branchA, systemPromptTokens],   // 200 tokens
+ *   [branchB, shortQueryTokens],     //  12 tokens
+ *   [branchC, longDocumentTokens],   // 800 tokens
+ * ]);
+ * // Bin-packed into ceil(1012 / nBatch) GPU dispatches
+ * ```
+ *
+ * @category Branching
+ */
+class BranchStore {
+    _ctx;
+    constructor(ctx) {
+        this._ctx = ctx;
+    }
+    /**
+     * Batched single-token commit for model-generated tokens
+     *
+     * Each tuple `[branch, token]` binds one token to one branch.
+     * Accepts each token into its branch's repeat-penalty window (for correct
+     * PPL measurement), then decodes all N tokens in a single llama_decode()
+     * call via decode_each and captures logits per-branch. Accept-first
+     * ordering with rollback: if decode throws, sampler/grammar/metrics are
+     * restored from clones taken before the accept.
+     *
+     * @param entries - Array of `[branch, token]` tuples (branches must not be disposed)
+     * @throws If any branch is disposed
+     */
+    async commit(entries) {
+        const handles = [];
+        const tokens = [];
+        for (const [branch, token] of entries) {
+            if (branch.disposed)
+                throw new Error('BranchStore.commit: branch is disposed');
+            handles.push(branch.handle);
+            tokens.push(token);
+        }
+        await this._ctx._storeCommit(handles, tokens);
+    }
+    /**
+     * Batched variable-length prefill for external tokens
+     *
+     * Each tuple `[branch, tokens]` binds a token array to one branch.
+     * Each branch can receive a different number of tokens — decode_scatter
+     * handles variable-length runs and auto-chunks to fit nBatch.
+     *
+     * Does NOT call accept_token — use for external/replayed tokens where
+     * repeat-penalty tracking is unwanted. For model-generated tokens,
+     * use {@link commit} instead.
+     *
+     * @param entries - Array of `[branch, tokens]` tuples (branches must not be disposed)
+     * @throws If any branch is disposed
+     */
+    async prefill(entries) {
+        const handles = [];
+        const tokenArrays = [];
+        for (const [branch, tokens] of entries) {
+            if (branch.disposed)
+                throw new Error('BranchStore.prefill: branch is disposed');
+            handles.push(branch.handle);
+            tokenArrays.push(tokens);
+        }
+        await this._ctx._storePrefill(handles, tokenArrays);
+    }
+    /**
+     * Retain only the winner branch — evict all other leases and free their slots.
+     *
+     * Nuclear operation: calls `kv::seq_keep` on the winner's seq_id (stripping all
+     * other sequences from KV cache in a single pass), then frees all loser slots
+     * and rebuilds the vacancy list. The winner's topology is reset (no parent, no children).
+     *
+     * @param winner - The branch to keep (must not be disposed, must hold a lease)
+     * @throws If winner is disposed or has no lease
+     */
+    async retainOnly(winner) {
+        if (winner.disposed)
+            throw new Error('BranchStore.retainOnly: winner is disposed');
+        this._ctx._storeRetainOnly(winner.handle);
+    }
+    get available() {
+        return this._ctx._storeAvailable();
+    }
+}
+exports.BranchStore = BranchStore;
+//# sourceMappingURL=BranchStore.js.map

package/dist/BranchStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BranchStore.js","sourceRoot":"","sources":["../src/BranchStore.ts"],"names":[],"mappings":";;;AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AACH,MAAa,WAAW;IACd,IAAI,CAAiB;IAE7B,YAAY,GAAmB;QAC7B,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;IAClB,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,MAAM,CAAC,OAA2B;QACtC,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,OAAO,EAAE,CAAC;YACtC,IAAI,MAAM,CAAC,QAAQ;gBAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;YAC/E,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC5B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;QACD,MAAM,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAChD,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,OAAO,CAAC,OAA6B;QACzC,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,MAAM,WAAW,GAAe,EAAE,CAAC;QACnC,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACvC,IAAI,MAAM,CAAC,QAAQ;gBAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;YAChF,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC5B,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC3B,CAAC;QACD,MAAM,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IACtD,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,UAAU,CAAC,MAAc;QAC7B,IAAI,MAAM,CAAC,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;QACnF,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;IACrC,CAAC;CACF;AA1ED,kCA0EC"}

package/dist/Rerank.d.ts

@@ -0,0 +1,38 @@
+import type { SessionContext, RerankProgress } from './types';
+export declare class Rerank {
+    private _ctx;
+    private _nSeqMax;
+    private _nCtx;
+    private _yesId;
+    private _noId;
+    private _prefixTokens;
+    private _midTokens;
+    private _suffixTokens;
+    private _pending;
+    private _draining;
+    private _disposed;
+    private constructor();
+    /**
+     * Create a Rerank instance from a pre-created SessionContext
+     *
+     * The caller is responsible for creating the context with appropriate
+     * settings (nSeqMax, nCtx, typeK, typeV). Rerank takes ownership of
+     * the context and will dispose it on `dispose()`.
+     *
+     * @param ctx - SessionContext configured for reranking
+     * @param opts - Capacity hints (nSeqMax, nCtx) — must match context creation params
+     */
+    static create(ctx: SessionContext, opts?: {
+        nSeqMax?: number;
+        nCtx?: number;
+    }): Promise<Rerank>;
+    score(query: string, documents: number[][], topK?: number): AsyncIterable<RerankProgress>;
+    tokenize(text: string): Promise<number[]>;
+    dispose(): void;
+    private _sortResults;
+    private _enqueue;
+    private _fillGroup;
+    private _drain;
+    private _rerankScore;
+}
+//# sourceMappingURL=Rerank.d.ts.map

package/dist/Rerank.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Rerank.d.ts","sourceRoot":"","sources":["../src/Rerank.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAgB,cAAc,EAAE,MAAM,SAAS,CAAC;AAmE5E,qBAAa,MAAM;IACjB,OAAO,CAAC,IAAI,CAAiB;IAC7B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,aAAa,CAAW;IAChC,OAAO,CAAC,UAAU,CAAW;IAC7B,OAAO,CAAC,aAAa,CAAW;IAChC,OAAO,CAAC,QAAQ,CAAwB;IACxC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAS;IAE1B,OAAO;IAoBP;;;;;;;;;OASG;WACU,MAAM,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAwBrG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,cAAc,CAAC;IA0BnF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAI/C,OAAO,IAAI,IAAI;IAUf,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,QAAQ;IAkBhB,OAAO,CAAC,UAAU;YAiBJ,MAAM;IA+CpB,OAAO,CAAC,YAAY;CAMrB"}

package/dist/Rerank.js

@@ -0,0 +1,220 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Rerank = void 0;
+const SYSTEM_PROMPT = 'Judge whether the Document meets the requirements based on the Query ' +
+    'and the Instruct provided. Note that the answer can only be "yes" or "no".';
+const USER_PREFIX = '<Instruct>: Given a web search query, retrieve relevant passages that answer the query\n\n' +
+    '<Query>: ';
+/** Simple async channel — _drain pushes, consumer pulls via for-await */
+function channel() {
+    const buffer = [];
+    let done = false;
+    let err = null;
+    let notify = null;
+    const wait = () => new Promise((r) => { notify = r; });
+    return {
+        push(value) {
+            buffer.push(value);
+            notify?.();
+            notify = null;
+        },
+        finish() {
+            done = true;
+            notify?.();
+            notify = null;
+        },
+        error(e) {
+            err = e;
+            notify?.();
+            notify = null;
+        },
+        iterable: {
+            [Symbol.asyncIterator]() {
+                return {
+                    async next() {
+                        while (buffer.length === 0 && !done && !err)
+                            await wait();
+                        if (err)
+                            throw err;
+                        if (buffer.length > 0)
+                            return { value: buffer.shift(), done: false };
+                        return { value: undefined, done: true };
+                    },
+                };
+            },
+        },
+    };
+}
+class Rerank {
+    _ctx;
+    _nSeqMax;
+    _nCtx;
+    _yesId;
+    _noId;
+    _prefixTokens;
+    _midTokens;
+    _suffixTokens;
+    _pending = [];
+    _draining = false;
+    _disposed = false;
+    constructor(ctx, nSeqMax, nCtx, yesId, noId, prefixTokens, midTokens, suffixTokens) {
+        this._ctx = ctx;
+        this._nSeqMax = nSeqMax;
+        this._nCtx = nCtx;
+        this._yesId = yesId;
+        this._noId = noId;
+        this._prefixTokens = prefixTokens;
+        this._midTokens = midTokens;
+        this._suffixTokens = suffixTokens;
+    }
+    /**
+     * Create a Rerank instance from a pre-created SessionContext
+     *
+     * The caller is responsible for creating the context with appropriate
+     * settings (nSeqMax, nCtx, typeK, typeV). Rerank takes ownership of
+     * the context and will dispose it on `dispose()`.
+     *
+     * @param ctx - SessionContext configured for reranking
+     * @param opts - Capacity hints (nSeqMax, nCtx) — must match context creation params
+     */
+    static async create(ctx, opts) {
+        const nSeqMax = opts?.nSeqMax ?? 8;
+        const nCtx = opts?.nCtx ?? ctx._storeKvPressure().nCtx;
+        const [yesId] = await ctx.tokenize('yes', false);
+        const [noId] = await ctx.tokenize('no', false);
+        const SENTINEL_Q = '\x00QUERY\x00';
+        const SENTINEL_D = '\x00DOC\x00';
+        const probe = await ctx.formatChat(JSON.stringify([
+            { role: 'system', content: SYSTEM_PROMPT },
+            { role: 'user', content: `${USER_PREFIX}${SENTINEL_Q}\n\n<Document>: ${SENTINEL_D}` },
+        ]), { addGenerationPrompt: true, enableThinking: false });
+        const p = probe.prompt;
+        const qi = p.indexOf(SENTINEL_Q);
+        const di = p.indexOf(SENTINEL_D);
+        const prefixTokens = await ctx.tokenize(p.slice(0, qi), true);
+        const midTokens = await ctx.tokenize(p.slice(qi + SENTINEL_Q.length, di), false);
+        const suffixTokens = await ctx.tokenize(p.slice(di + SENTINEL_D.length), false);
+        return new Rerank(ctx, nSeqMax, nCtx, yesId, noId, prefixTokens, midTokens, suffixTokens);
+    }
+    score(query, documents, topK) {
+        if (this._disposed)
+            throw new Error('Rerank disposed');
+        const self = this;
+        const ch = channel();
+        (async () => {
+            try {
+                const queryTokens = await self._ctx.tokenize(query, false);
+                const shared = [...self._prefixTokens, ...queryTokens, ...self._midTokens];
+                const maxDoc = Math.floor(self._nCtx / self._nSeqMax) - shared.length - self._suffixTokens.length;
+                const tokenArrays = documents.map((doc) => {
+                    const trimmed = doc.length > maxDoc ? doc.slice(0, maxDoc) : doc;
+                    return [...shared, ...trimmed, ...self._suffixTokens];
+                });
+                self._enqueue(tokenArrays, topK, ch.push, ch.finish, ch.error);
+            }
+            catch (err) {
+                ch.error(err instanceof Error ? err : new Error(String(err)));
+            }
+        })();
+        return ch.iterable;
+    }
+    async tokenize(text) {
+        return this._ctx.tokenize(text, false);
+    }
+    dispose() {
+        this._disposed = true;
+        const err = new Error('Rerank disposed');
+        for (const req of this._pending)
+            req.error(err);
+        this._pending.length = 0;
+        this._ctx.dispose();
+    }
+    // ── Queue internals ──────────────────────────────────────────
+    _sortResults(scores, topK) {
+        const sorted = scores
+            .map((score, index) => ({ score: Math.round(score * 1000) / 1000, index }))
+            .sort((a, b) => b.score - a.score);
+        return topK != null ? sorted.slice(0, topK) : sorted;
+    }
+    _enqueue(tokenArrays, topK, push, finish, error) {
+        this._pending.push({
+            tokenArrays, cursor: 0,
+            scores: new Array(tokenArrays.length),
+            filled: 0,
+            topK,
+            total: tokenArrays.length,
+            push, finish, error,
+        });
+        this._drain();
+    }
+    _fillGroup() {
+        const group = [];
+        let added = true;
+        while (group.length < this._nSeqMax && added) {
+            added = false;
+            for (let r = 0; r < this._pending.length && group.length < this._nSeqMax; r++) {
+                const req = this._pending[r];
+                if (req.cursor < req.tokenArrays.length) {
+                    group.push({ reqIdx: r, promptIdx: req.cursor, tokens: req.tokenArrays[req.cursor] });
+                    req.cursor++;
+                    added = true;
+                }
+            }
+        }
+        return group;
+    }
+    async _drain() {
+        if (this._draining)
+            return;
+        this._draining = true;
+        try {
+            while (this._pending.length > 0) {
+                const group = this._fillGroup();
+                if (group.length === 0)
+                    break;
+                let logits;
+                try {
+                    logits = await this._ctx._scoreGroup(group.map((g) => g.tokens));
+                }
+                catch (err) {
+                    const error = err instanceof Error ? err : new Error(String(err));
+                    for (const req of this._pending)
+                        req.error(error);
+                    this._pending.length = 0;
+                    return;
+                }
+                // Track which requests got new scores this group
+                const touched = new Set();
+                for (let i = 0; i < group.length; i++) {
+                    const req = this._pending[group[i].reqIdx];
+                    req.scores[group[i].promptIdx] = this._rerankScore(logits[i]);
+                    req.filled++;
+                    touched.add(group[i].reqIdx);
+                }
+                // Push progress for each request that advanced, finish completed ones
+                for (let r = this._pending.length - 1; r >= 0; r--) {
+                    const req = this._pending[r];
+                    if (!touched.has(r))
+                        continue;
+                    const results = this._sortResults(req.scores, req.topK);
+                    req.push({ filled: req.filled, total: req.total, results });
+                    if (req.filled === req.total) {
+                        req.finish();
+                        this._pending.splice(r, 1);
+                    }
+                }
+            }
+        }
+        finally {
+            this._draining = false;
+        }
+    }
+    _rerankScore(logits) {
+        const max = Math.max(logits[this._yesId], logits[this._noId]);
+        const yesExp = Math.exp(logits[this._yesId] - max);
+        const noExp = Math.exp(logits[this._noId] - max);
+        return yesExp / (yesExp + noExp);
+    }
+}
+exports.Rerank = Rerank;
+//# sourceMappingURL=Rerank.js.map

package/dist/Rerank.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Rerank.js","sourceRoot":"","sources":["../src/Rerank.ts"],"names":[],"mappings":"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"}

package/dist/Session.d.ts

@@ -0,0 +1,74 @@
+import type { Branch } from './Branch';
+import type { BranchStore } from './BranchStore';
+import type { SessionContext } from './types';
+/**
+ * Session - Trunk lifecycle + conversation delta helpers
+ *
+ * Owns the current "trunk" branch and provides promote() to crown a winner,
+ * plus delta helpers that centralize the sep + formatChat + tokenize + prefill
+ * pattern for injecting new turns into an ongoing conversation.
+ *
+ * Session does NOT own the SessionContext or BranchStore — the consumer
+ * creates those and passes them in. dispose() prunes trunk only.
+ *
+ * @example
+ * ```typescript
+ * const session = new Session({ ctx, store });
+ * session.trunk = initialBranch;
+ *
+ * // After verification, promote the best attempt
+ * await session.promote(bestAttempt.branch);
+ *
+ * // Inject a user turn and generate
+ * await session.prefillUser('What about X?');
+ * for await (const { text } of session.trunk) {
+ *   process.stdout.write(text);
+ * }
+ *
+ * // Cleanup
+ * await session.dispose();
+ * ctx.dispose();
+ * ```
+ *
+ * @category Branching
+ */
+export declare class Session {
+    private _ctx;
+    private _store;
+    private _trunk;
+    constructor({ ctx, store }: {
+        ctx: SessionContext;
+        store: BranchStore;
+    });
+    /** Current trunk branch */
+    get trunk(): Branch | null;
+    /** Assign initial trunk (no promote) */
+    set trunk(branch: Branch | null);
+    /**
+     * Promote a winner to trunk — retainOnly + reassign
+     *
+     * Safe even if winner is the only branch (resets topology, no-op on KV).
+     */
+    promote(winner: Branch): Promise<void>;
+    /**
+     * Dispose trunk only — consumer owns ctx and other resources
+     */
+    dispose(): Promise<void>;
+    /**
+     * Prefill a user turn into trunk
+     *
+     * @param content - User message content
+     * @param opts - Optional tools JSON string
+     */
+    prefillUser(content: string, opts?: {
+        tools?: string;
+    }): Promise<void>;
+    /**
+     * Prefill a tool result turn into trunk
+     *
+     * @param resultStr - JSON-stringified tool result
+     * @param callId - Tool call ID
+     */
+    prefillToolResult(resultStr: string, callId: string): Promise<void>;
+}
+//# sourceMappingURL=Session.d.ts.map

package/dist/Session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Session.d.ts","sourceRoot":"","sources":["../src/Session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,IAAI,CAAiB;IAC7B,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,MAAM,CAAgB;gBAElB,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE;QAAE,GAAG,EAAE,cAAc,CAAC;QAAC,KAAK,EAAE,WAAW,CAAA;KAAE;IAMvE,2BAA2B;IAC3B,IAAI,KAAK,IAAI,MAAM,GAAG,IAAI,CAEzB;IAED,wCAAwC;IACxC,IAAI,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAE9B;IAED;;;;OAIG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK5C;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAO9B;;;;;OAKG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAKhF;;;;;OAKG;IACG,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAI1E"}