@mlx-node/server 0.0.0

package/dist/mappers/request.js

@@ -0,0 +1,206 @@
+/** OpenAI Responses API request → internal `ChatMessage[]` + `ChatConfig`. */
+function resolveContent(content) {
+    if (typeof content === 'string')
+        return content;
+    const parts = [];
+    for (const p of content) {
+        if (p.type === 'input_text') {
+            parts.push(p.text);
+        }
+        else {
+            throw new Error(`Unsupported content part type: "${p.type}"`);
+        }
+    }
+    return parts.join('');
+}
+/** NAPI `ToolDefinition` requires `parameters.properties` to be a JSON string. */
+function mapTool(tool) {
+    if (tool.type !== 'function') {
+        throw new Error(`Unsupported tool type: "${tool.type}"`);
+    }
+    const params = tool.parameters;
+    return {
+        type: 'function',
+        function: {
+            name: tool.name,
+            description: tool.description,
+            parameters: params
+                ? {
+                    type: 'object',
+                    properties: params['properties'] ? JSON.stringify(params['properties']) : undefined,
+                    required: Array.isArray(params['required']) ? params['required'] : undefined,
+                }
+                : undefined,
+        },
+    };
+}
+export function mapRequest(req, priorMessages) {
+    const messages = [];
+    if (req.instructions) {
+        messages.push({ role: 'system', content: req.instructions });
+    }
+    if (priorMessages) {
+        messages.push(...priorMessages);
+    }
+    // Coalesce a `message + function_call+` run (or a pure `function_call+` run)
+    // into ONE assistant `ChatMessage` carrying both `content` and `toolCalls`.
+    // `ChatSession.sendStream()` appends exactly one assistant message per turn,
+    // and `validateAndCanonicalizeHistoryToolOrder` requires each fan-out's
+    // `toolCalls` to pair 1:1 with the trailing tool block — splitting would
+    // reshape the conversation and make the walker reject the turn as orphaned.
+    // A `message` item immediately after a `function_call` starts a new turn.
+    if (typeof req.input === 'string') {
+        messages.push({ role: 'user', content: req.input });
+    }
+    else {
+        let prevItemType = null;
+        for (const item of req.input) {
+            if (item == null || typeof item !== 'object') {
+                throw new Error('Each input item must be a non-null object');
+            }
+            const itemType = item.type ?? 'message';
+            if (itemType === 'message') {
+                const msg = item;
+                // OpenAI "developer" maps to our "system".
+                const role = msg.role === 'developer' ? 'system' : msg.role;
+                if (role !== 'user' && role !== 'assistant' && role !== 'system') {
+                    throw new Error(`Unsupported message role: "${msg.role}"`);
+                }
+                messages.push({
+                    role,
+                    content: resolveContent(msg.content),
+                });
+            }
+            else if (itemType === 'function_call') {
+                // Coalesce onto the preceding assistant turn — see the loop header.
+                const fc = item;
+                const last = messages[messages.length - 1];
+                const canCoalesce = (prevItemType === 'function_call' || prevItemType === 'message') &&
+                    last !== undefined &&
+                    last.role === 'assistant';
+                if (canCoalesce) {
+                    if (last.toolCalls === undefined) {
+                        last.toolCalls = [];
+                    }
+                    last.toolCalls.push({ name: fc.name, arguments: fc.arguments, id: fc.call_id });
+                }
+                else {
+                    messages.push({
+                        role: 'assistant',
+                        content: '',
+                        toolCalls: [{ name: fc.name, arguments: fc.arguments, id: fc.call_id }],
+                    });
+                }
+            }
+            else if (itemType === 'function_call_output') {
+                const fco = item;
+                messages.push({
+                    role: 'tool',
+                    content: fco.output,
+                    toolCallId: fco.call_id,
+                });
+            }
+            else {
+                throw new Error(`Unsupported input item type: "${itemType}"`);
+            }
+            prevItemType = itemType;
+        }
+    }
+    const config = {
+        reportPerformance: true,
+    };
+    if (req.max_output_tokens != null) {
+        config.maxNewTokens = req.max_output_tokens;
+    }
+    if (req.temperature != null) {
+        config.temperature = req.temperature;
+    }
+    if (req.top_p != null) {
+        config.topP = req.top_p;
+    }
+    if (req.reasoning?.effort) {
+        config.reasoningEffort = req.reasoning.effort;
+    }
+    if (req.tools && req.tools.length > 0) {
+        if (req.tool_choice === 'none') {
+            // Caller disabled tool use.
+        }
+        else if (typeof req.tool_choice === 'object' && req.tool_choice?.type === 'function') {
+            const targetName = req.tool_choice.name;
+            const matched = req.tools.filter((t) => t.name === targetName);
+            if (matched.length > 0) {
+                config.tools = matched.map(mapTool);
+            }
+        }
+        else {
+            config.tools = req.tools.map(mapTool);
+        }
+    }
+    if (priorMessages && priorMessages.length > 0) {
+        config.reuseCache = true;
+    }
+    return { messages, config };
+}
+/**
+ * Reconstruct `ChatMessage[]` from a stored response chain. Each record
+ * stores `inputJson` (messages sent) and `outputJson` (output items); we
+ * interleave them.
+ */
+export function reconstructMessagesFromChain(chain) {
+    const messages = [];
+    for (const record of chain) {
+        const inputMessages = JSON.parse(record.inputJson);
+        messages.push(...inputMessages);
+        const outputItems = JSON.parse(record.outputJson);
+        let assistantText = '';
+        let thinkingText = '';
+        // Track presence vs. content separately: an empty-text `message` item
+        // still represents a real successful turn (the hot-path `ChatSession`
+        // always appends an assistant message per turn), so cold replay must
+        // preserve it or `primeHistory` will reshape the conversation.
+        let hadMessageItem = false;
+        let hadReasoningItem = false;
+        const toolCalls = [];
+        for (const item of outputItems) {
+            if (item.type === 'message') {
+                hadMessageItem = true;
+                if (item.content) {
+                    assistantText += item.content.map((c) => c.text).join('');
+                }
+            }
+            else if (item.type === 'reasoning') {
+                hadReasoningItem = true;
+                if (item.summary) {
+                    thinkingText += item.summary.map((s) => s.text).join('');
+                }
+            }
+            else if (item.type === 'function_call') {
+                toolCalls.push({
+                    name: item.name,
+                    arguments: item.arguments,
+                    id: item.call_id,
+                });
+            }
+        }
+        // Preserve the assistant turn whenever the record carried any assistant-facing
+        // item — message (even empty), reasoning, or function_call — because the hot-path
+        // `ChatSession` always appends one assistant message per completed turn.
+        // Keying on accumulated content would silently drop blank successful turns and
+        // reshape the replayed conversation. Records with no assistant items (input-only)
+        // are still skipped so we don't fabricate turns the live session never generated.
+        if (hadMessageItem || hadReasoningItem || toolCalls.length > 0) {
+            const assistantMsg = {
+                role: 'assistant',
+                content: assistantText,
+            };
+            if (thinkingText) {
+                assistantMsg.reasoningContent = thinkingText;
+            }
+            if (toolCalls.length > 0) {
+                assistantMsg.toolCalls = toolCalls;
+            }
+            messages.push(assistantMsg);
+        }
+    }
+    return messages;
+}

package/dist/mappers/response.d.ts

@@ -0,0 +1,13 @@
+/** ChatResult / ChatStreamEvent → OpenAI Responses API output. */
+import type { ChatResult } from '@mlx-node/core';
+import type { OutputItem, ResponseObject, ResponsesAPIRequest, ResponseUsage } from '../types.js';
+export declare function genId(prefix: string): string;
+export declare function mapFinishReasonToStatus(finishReason: string): 'completed' | 'incomplete';
+export declare function buildOutputItems(result: ChatResult): OutputItem[];
+export declare function buildUsage(result: ChatResult): ResponseUsage;
+/** Concatenate all `output_text` parts from message items. */
+export declare function computeOutputText(items: OutputItem[]): string;
+export declare function buildResponseObject(result: ChatResult, req: ResponsesAPIRequest, responseId: string, previousResponseId?: string): ResponseObject;
+/** Build an in-progress ResponseObject for `response.created` / `response.in_progress`, before any output exists. */
+export declare function buildPartialResponse(req: ResponsesAPIRequest, responseId: string, previousResponseId?: string): ResponseObject;
+//# sourceMappingURL=response.d.ts.map

package/dist/mappers/response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/mappers/response.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAIlE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,OAAO,KAAK,EAGV,UAAU,EAEV,cAAc,EACd,mBAAmB,EACnB,aAAa,EACd,MAAM,aAAa,CAAC;AAErB,wBAAgB,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,WAAW,GAAG,YAAY,CAOxF;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,EAAE,CAwCjE;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAO5D;AAED,8DAA8D;AAC9D,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,MAAM,CAU7D;AAED,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,mBAAmB,EACxB,UAAU,EAAE,MAAM,EAClB,kBAAkB,CAAC,EAAE,MAAM,GAC1B,cAAc,CAwBhB;AAED,qHAAqH;AACrH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,mBAAmB,EACxB,UAAU,EAAE,MAAM,EAClB,kBAAkB,CAAC,EAAE,MAAM,GAC1B,cAAc,CAqBhB"}

package/dist/mappers/response.js

@@ -0,0 +1,116 @@
+/** ChatResult / ChatStreamEvent → OpenAI Responses API output. */
+import { randomUUID } from 'node:crypto';
+export function genId(prefix) {
+    return `${prefix}${randomUUID().replaceAll('-', '')}`;
+}
+export function mapFinishReasonToStatus(finishReason) {
+    switch (finishReason) {
+        case 'length':
+            return 'incomplete';
+        default:
+            return 'completed';
+    }
+}
+export function buildOutputItems(result) {
+    const items = [];
+    if (result.thinking) {
+        const reasoningItem = {
+            id: genId('rs_'),
+            type: 'reasoning',
+            summary: [{ type: 'summary_text', text: result.thinking }],
+        };
+        items.push(reasoningItem);
+    }
+    const okToolCalls = result.toolCalls.filter((t) => t.status === 'ok');
+    // Always emit a message item (possibly with empty text) unless there are tool calls and no text.
+    if (result.text || okToolCalls.length === 0) {
+        const messageItem = {
+            id: genId('msg_'),
+            type: 'message',
+            role: 'assistant',
+            status: mapFinishReasonToStatus(result.finishReason),
+            content: [{ type: 'output_text', text: result.text, annotations: [] }],
+        };
+        items.push(messageItem);
+    }
+    for (const tc of okToolCalls) {
+        const callId = tc.id ?? genId('call_');
+        const fcItem = {
+            id: genId('fc_'),
+            type: 'function_call',
+            call_id: callId,
+            name: tc.name,
+            arguments: typeof tc.arguments === 'string' ? tc.arguments : JSON.stringify(tc.arguments),
+            status: 'completed',
+        };
+        items.push(fcItem);
+    }
+    return items;
+}
+export function buildUsage(result) {
+    return {
+        input_tokens: result.promptTokens,
+        output_tokens: result.numTokens,
+        output_tokens_details: { reasoning_tokens: result.reasoningTokens },
+        total_tokens: result.promptTokens + result.numTokens,
+    };
+}
+/** Concatenate all `output_text` parts from message items. */
+export function computeOutputText(items) {
+    const parts = [];
+    for (const item of items) {
+        if (item.type === 'message') {
+            for (const c of item.content) {
+                parts.push(c.text);
+            }
+        }
+    }
+    return parts.join('');
+}
+export function buildResponseObject(result, req, responseId, previousResponseId) {
+    const output = buildOutputItems(result);
+    const status = mapFinishReasonToStatus(result.finishReason);
+    return {
+        id: responseId,
+        object: 'response',
+        created_at: Math.floor(Date.now() / 1000),
+        status,
+        model: req.model,
+        output,
+        output_text: computeOutputText(output),
+        error: null,
+        incomplete_details: status === 'incomplete' ? { reason: 'max_output_tokens' } : null,
+        usage: buildUsage(result),
+        instructions: req.instructions ?? null,
+        temperature: req.temperature ?? null,
+        top_p: req.top_p ?? null,
+        max_output_tokens: req.max_output_tokens ?? null,
+        tools: req.tools ?? [],
+        tool_choice: req.tool_choice ?? null,
+        reasoning: req.reasoning ?? null,
+        previous_response_id: previousResponseId ?? null,
+    };
+}
+/** Build an in-progress ResponseObject for `response.created` / `response.in_progress`, before any output exists. */
+export function buildPartialResponse(req, responseId, previousResponseId) {
+    return {
+        id: responseId,
+        object: 'response',
+        created_at: Math.floor(Date.now() / 1000),
+        status: 'in_progress',
+        model: req.model,
+        output: [],
+        output_text: '',
+        error: null,
+        incomplete_details: null,
+        usage: { input_tokens: 0, output_tokens: 0, output_tokens_details: { reasoning_tokens: 0 }, total_tokens: 0 },
+        instructions: req.instructions ?? null,
+        temperature: req.temperature ?? null,
+        top_p: req.top_p ?? null,
+        max_output_tokens: req.max_output_tokens ?? null,
+        tools: req.tools ?? [],
+        tool_choice: req.tool_choice ?? null,
+        reasoning: req.reasoning ?? null,
+        previous_response_id: previousResponseId ?? null,
+    };
+}

package/dist/pending-writes.d.ts

@@ -0,0 +1,337 @@
+/**
+ * PendingResponseWrites — per-store in-memory index of response
+ * records whose `ResponseStore.store(...)` promise has been initiated
+ * but has not yet resolved.
+ *
+ * ## Why this exists
+ *
+ * The responses endpoint starts `store.store(record)` synchronously
+ * inside the per-model `withExclusive` block (so the tracker observes
+ * the in-flight write before the mutex releases) but does NOT await
+ * it on the critical path. Without this tracker, a client that fires
+ * a follow-up request carrying `previous_response_id: A` immediately
+ * after seeing `response.completed` could race the off-lock
+ * `store.store()` for A and be rejected with a spurious
+ * `404 Previous response not found` because `getChain()` had not yet
+ * seen the row.
+ *
+ * The chain-lookup path consults `awaitPending(id)` BEFORE treating
+ * `getChain(id).length === 0` as a 404. If a write is still in flight,
+ * it awaits and retries `getChain`; the retry is guaranteed to see
+ * the row because the promise resolves only after the store's own
+ * serialization queue has accepted the insert.
+ *
+ * ## Semantics
+ *
+ * `track(id, promise)` registers `promise` under `id` and removes the
+ * entry when the promise settles (fulfill OR reject — a failed write
+ * leaves the tracker empty and the subsequent `getChain()` returns
+ * empty, which is the correct 404 shape).
+ *
+ * `awaitPending(id)` returns the tracked in-flight promise, or
+ * undefined. It is the SAME promise that was registered; our removal
+ * handler is attached via `.finally(...)` so the caller's rejection
+ * behaviour is unaffected. Callers typically swallow rejections with
+ * `await …catch(() => {})` before retrying `getChain()` because the
+ * rejection is already surfaced through the registering awaiter.
+ *
+ * ## Hard-timeout marker state
+ *
+ * When the responses-endpoint breaker decides a pending write is
+ * wedged it calls `markHardTimedOut(id, ttlMs, absoluteExpiresAt)`,
+ * which removes the id from `pending` (so the closure chain is
+ * reclaimable) and adds it to a lightweight `hardTimedOut` map. The
+ * continuation path then classifies a missing chain as retryable 503
+ * `storage_timeout` instead of permanent 404 while the marker is live.
+ *
+ * Marker lifetime is bounded by:
+ *
+ *   min(write settlement, last continuation + TTL, absoluteExpiresAt)
+ *
+ * Five cleanup/refresh paths keep memory bounded and classification
+ * honest:
+ *
+ *   1. Fast path — `track()`'s `.finally(...)` deletes the marker as
+ *      soon as the wedged write settles.
+ *   2. Read-refresh path — `isHardTimedOut(id)` slides `expiresAt`
+ *      forward by `ttlMs` on every live hit (clamped at
+ *      `absoluteExpiresAt`). Actively retried chains stay recoverable
+ *      as long as the underlying write might still land.
+ *   3. Read-expire path — a full TTL elapse without refresh lazily
+ *      deletes the entry and classifies the id as permanent 404.
+ *   4. Read-absolute-cap path — once `Date.now() >= absoluteExpiresAt`,
+ *      the marker is deleted unconditionally. `ResponseStore.getChain()`
+ *      hides the row past its own row TTL, so the retryable-503
+ *      classification would be factually wrong.
+ *   5. Write-sweep path — `markHardTimedOut()` drains expired entries
+ *      before inserting, bounded to `MAX_SWEEP_PER_INSERT` visits per
+ *      call to keep the transition O(1) amortized even when the map
+ *      is large. `isHardTimedOut()` moves refreshed entries to the
+ *      Map tail so the bounded sweep cannot be starved by a stable
+ *      head cohort of hot entries (natural LRU behaviour).
+ *
+ * The caller-side `absoluteExpiresAt` is the MINIMUM `expiresAt`
+ * across the whole resolved chain, not just the child record.
+ * `ResponseStore.getChain()` walks ancestors and aborts on the first
+ * expired link (see `crates/mlx-db/src/response_store/reader.rs:44-59`),
+ * so a child whose parent expires sooner is unrecoverable at the
+ * parent's expiry — not the child's. This module just receives the
+ * min-clamped value.
+ *
+ * ## Pending-entry earliest-expiry metadata
+ *
+ * The pre-breaker `awaitPending` timeout/probe path in `responses.ts`
+ * would otherwise classify any unresolved pending write as retryable
+ * `storage_timeout`, even when the resolved chain's earliest ancestor
+ * has already expired. A continuation whose parent is already past
+ * its row TTL cannot ever succeed via `getChain()`, so looping the
+ * client on 503 until the hard breaker fires is wasted.
+ *
+ * `track(id, promise, earliestExpiresAtMs?)` records the earliest
+ * recoverable expiry alongside the tracked promise in a per-id side
+ * map (`earliestExpiresByPending`). `getEarliestExpiresAtMs(id)`
+ * exposes it so the endpoint can short-circuit to 404 once
+ * `Date.now() >= earliestExpiresAtMs`. The side map is keyed
+ * identically to `pending` and cleared on the same `.finally(...)`
+ * hook — no extra lifecycle surface.
+ *
+ * ## Scope
+ *
+ * One tracker per `ResponseStore` instance is attached via a
+ * `WeakMap`, so callers never need to thread the tracker through the
+ * handler plumbing explicitly. This keeps the same (store, tracker)
+ * pair alive for the lifetime of the store and avoids leaks across
+ * test suites that recreate the store per describe block.
+ */
+/**
+ * Per-store tracker for in-flight `store.store(...)` writes.
+ *
+ * Thread-safety: Node.js is single-threaded within one event loop
+ * tick, so the internal `Map` is safe against concurrent mutation by
+ * design. Every mutation (`track`, `awaitPending`, `.finally(...)`
+ * cleanup) runs synchronously within a tick.
+ */
+export declare class PendingResponseWrites {
+    private readonly pending;
+    /**
+     * Per-pending-entry scalar recording the EARLIEST recoverable
+     * wall-clock expiry across (record + resolved ancestor chain) at
+     * `track()` time. Keyed identically to `pending` and cleared on
+     * the same `.finally(...)` settlement hook.
+     *
+     * The pre-breaker `awaitPending` timeout/probe path consults this
+     * via `getEarliestExpiresAtMs(id)`: once `Date.now()` has passed
+     * the earliest ancestor expiry, `getChain()` can never succeed,
+     * so the continuation short-circuits to 404 rather than looping
+     * the client on retryable 503.
+     *
+     * Optional: callers that pass `undefined` do not populate the
+     * side map; `getEarliestExpiresAtMs(id)` then returns `undefined`
+     * and the caller falls back to emitting retryable 503.
+     */
+    private readonly earliestExpiresByPending;
+    /**
+     * Ids that crossed the hard-timeout breaker in `responses.ts`
+     * while their `store.store(...)` promise was still unresolved.
+     *
+     * Each entry records `{ expiresAt, ttlMs, absoluteExpiresAt }` in
+     * epoch-ms. `expiresAt` is the TTL-based sliding window;
+     * `absoluteExpiresAt` is the record row's own wall-clock expiry
+     * (`record.expiresAt * 1000`). See the module header for the full
+     * cleanup/refresh path inventory.
+     *
+     * Invariant: a marker is only meaningful for the SPECIFIC write
+     * that was live when `markHardTimedOut` was called. If a later
+     * `track(id, newPromise)` reuses the same id after a marker was
+     * set, the original promise's `.finally(...)` will still clear
+     * the marker on its settlement (clearing the wrong state for the
+     * new promise). In practice the responses endpoint scopes
+     * response ids to a single persist each, so this collision cannot
+     * arise.
+     */
+    private readonly hardTimedOut;
+    /**
+     * Per-call visit budget for the opportunistic sweep invoked from
+     * `markHardTimedOut()`. Without a cap, refresh-on-read could keep
+     * the map arbitrarily large and every transition would pay O(N) on
+     * the main event loop (amortized O(N^2) across N wedged writes).
+     *
+     * Cap of 64 makes each transition O(1) with a small constant.
+     * JavaScript `Map` iterates in insertion order, so the sweep
+     * naturally drains the oldest markers first — which is where
+     * same-TTL expiries cluster. A backlog of K expired markers drains
+     * fully across ceil(K / 64) subsequent inserts, adequate because
+     * the read-path deletions are the authoritative cleanup signals
+     * for ids that actually receive continuation traffic.
+     *
+     * NOTE: the budget is a VISIT limit, not a delete limit. We stop
+     * after visiting MAX_SWEEP_PER_INSERT entries regardless of how
+     * many were expired, so cost stays bounded even when none of the
+     * first 64 entries are expired.
+     */
+    private static readonly MAX_SWEEP_PER_INSERT;
+    /**
+     * Register an in-flight write under `id`. The caller must pass the
+     * raw `Promise<void>` returned by `store.store(record)` BEFORE
+     * awaiting it — otherwise the race window we are trying to close
+     * reopens.
+     *
+     * The tracker attaches its own `.finally(...)` handler to remove
+     * the entry when the promise settles. The caller's own handling of
+     * the promise (await / catch / log) is unaffected because
+     * `.finally` returns a new promise chain that does not steal the
+     * rejection.
+     *
+     * `earliestExpiresAtMs` is the EARLIEST wall-clock expiry (epoch-ms)
+     * across the record being persisted AND every resolved ancestor in
+     * its chain. When provided, it is stored in
+     * `earliestExpiresByPending` so the pre-breaker `awaitPending`
+     * timeout/probe path can short-circuit to 404 once
+     * `Date.now() >= earliestExpiresAtMs` rather than emit retryable
+     * 503 for a chain that cannot be recovered via `getChain()`.
+     * `Number.isFinite(...)` guards for rows lacking explicit
+     * `expiresAt`.
+     */
+    track(id: string, writePromise: Promise<void>, earliestExpiresAtMs?: number): void;
+    /**
+     * Return the in-flight write promise for `id`, or `undefined` if
+     * none is tracked. Callers typically await with rejection
+     * suppressed (the tracker promise's rejection is already handled
+     * by the separate awaiter that initiated the write) and then
+     * retry `store.getChain(id)`.
+     */
+    awaitPending(id: string): Promise<void> | undefined;
+    /**
+     * Return the EARLIEST wall-clock expiry (epoch-ms) captured
+     * alongside the in-flight write for `id` at `track()` time, or
+     * `undefined` if no pending write is tracked and no live marker
+     * covers this id.
+     *
+     * Consulted by the pre-breaker `awaitPending` timeout/probe path in
+     * `responses.ts` to distinguish a transient storage slowdown
+     * (retryable 503) from an unrecoverable chain where the earliest
+     * ancestor has already aged out (permanent 404).
+     *
+     * Falls back to the marker's `absoluteExpiresAt` when the pending
+     * entry has already been drained by `markHardTimedOut()` — otherwise
+     * a waiter that straddled the `pending -> hardTimedOut` transition
+     * would see `undefined` and fall through to retryable 503 for an
+     * unrecoverable chain. Both sites are fed
+     * `min(recordExpiresAtMs, chainEarliestExpiresAtMs)` by
+     * `initiatePersist` in `responses.ts`, so this is lossless.
+     *
+     * The fallback is gated on the shared `isMarkerLive` predicate so
+     * a marker whose TTL or absolute expiry has already passed cannot
+     * hand back a future scalar that contradicts `isHardTimedOut()`.
+     * Dead markers return `0` (sentinel meaning "already expired") —
+     * the consumer's `Date.now() >= earliestMs` guard always trips for
+     * `0`, producing a permanent 404 instead of falling through to the
+     * retryable-503 branch. This read path stays side-effect-free;
+     * `sweepExpired()` is the authoritative reaper.
+     */
+    getEarliestExpiresAtMs(id: string): number | undefined;
+    /**
+     * Shared, side-effect-free liveness predicate for hard-timeout
+     * markers: live iff `now < expiresAt` AND `now < absoluteExpiresAt`.
+     *
+     * Extracted so `getEarliestExpiresAtMs()` (read-only) and the
+     * mutating `isHardTimedOut()` poll agree on liveness without either
+     * invoking the other — `isHardTimedOut()` has refresh + move-to-tail
+     * side effects only correct for the polling-side caller.
+     */
+    private static isMarkerLive;
+    /**
+     * Transition a pending entry to the hard-timed-out marker state.
+     *
+     * Called by the hard-timeout breaker in `responses.ts` when an
+     * in-flight `store.store(...)` has crossed the hard timeout and is
+     * presumed wedged. The `pending` entry is removed so `awaitPending`
+     * stops handing out the stale promise and the closure chain is
+     * reclaimable. The id is added to the marker map so the
+     * continuation path classifies missing chains as retryable 503
+     * `storage_timeout` instead of permanent 404 while the marker is
+     * live.
+     *
+     * `ttlMs` caps the marker lifetime independently of whether the
+     * underlying write settles. The caller (`responses.ts`) reads it
+     * from `MLX_HARD_TIMEOUT_MARKER_TTL_MS`; passing it in keeps this
+     * module env-free.
+     *
+     * `absoluteExpiresAt` is the response record's row expiry
+     * (`record.expiresAt * 1000`). The initial expiry is
+     * `min(Date.now() + ttlMs, absoluteExpiresAt)` so a short-lived
+     * record cannot have its marker outlive its row.
+     * `isHardTimedOut()` also consults `absoluteExpiresAt` on every
+     * read and hard-stops at that bound regardless of refreshes.
+     *
+     * Returns true if the id was an active pending entry and was moved
+     * to the marker; false if no pending entry existed at call time.
+     * A false return does NOT add the id to the marker — a marker
+     * without a backing promise has no fast cleanup signal (beyond
+     * TTL / absolute cap) and would produce spurious retryable-503
+     * signals in the meantime if the caller mis-routes ids.
+     */
+    markHardTimedOut(id: string, ttlMs: number, absoluteExpiresAt: number): boolean;
+    /**
+     * Drain expired marker entries (`expiresAt <= now` or
+     * `absoluteExpiresAt <= now`). Visits at most
+     * `MAX_SWEEP_PER_INSERT` entries per call so a caller cannot
+     * trigger an unbounded linear walk. `Map` insertion order makes
+     * this drain the oldest (most likely expired) markers first. The
+     * budget is a VISIT limit, not a delete limit.
+     */
+    private sweepExpired;
+    /**
+     * Whether `id` is currently flagged as hard-timed-out. Used by the
+     * `previous_response_id` continuation path to classify a missing
+     * chain as retryable 503 `storage_timeout` vs. permanent 404.
+     *
+     * Read-path cleanup + refresh semantics:
+     *
+     *   - Absolute cap is authoritative: once `now >= absoluteExpiresAt`
+     *     the marker is deleted unconditionally. `ResponseStore.getChain()`
+     *     hides the row past its own row TTL, so retryable-503 would
+     *     lie to the client.
+     *   - TTL-expired: lazy delete + return false.
+     *   - Live hit: refresh `expiresAt = min(now + ttlMs, absoluteExpiresAt)`
+     *     so actively-retried chains stay recoverable while the write
+     *     might still land, without ever outliving the row.
+     *   - On every live hit, move the entry to the Map tail (O(1)
+     *     `delete` + `set` using insertion-order semantics). Without
+     *     the rotation a stable head cohort of hot refreshed entries
+     *     could indefinitely block the bounded `sweepExpired()` from
+     *     reaching expired markers behind them. LRU rotation lets the
+     *     sweep make forward progress.
+     */
+    isHardTimedOut(id: string): boolean;
+    /** Number of writes currently in flight. Primarily for tests. */
+    get size(): number;
+    /**
+     * Number of ids currently in the hard-timed-out marker state.
+     * Primarily for tests. Delegates to the shared `sweepExpired()`
+     * helper so read-count and write-sweep stay in lockstep.
+     *
+     * Caveat: because the sweep is bounded (`MAX_SWEEP_PER_INSERT`
+     * visits per call), the reported size may include still-present
+     * expired entries that sit past the per-call visit budget.
+     * Callers needing exact reclaimed-count semantics should drive
+     * further `markHardTimedOut()` inserts (each drains another
+     * batch) or call `isHardTimedOut(id)` directly — the read-path
+     * deletion is authoritative and unbounded per-id.
+     */
+    get hardTimedOutSize(): number;
+    /**
+     * Number of ids currently holding a scalar entry in the
+     * pending-side earliest-expiry map. Primarily for tests —
+     * regressions that need to validate the pending-side map is
+     * drained (independent of the marker-map fallback in
+     * `getEarliestExpiresAtMs`) require a direct readout.
+     */
+    get earliestExpiresByPendingSize(): number;
+}
+/**
+ * Fetch (or lazily create) the tracker for a given store. Always
+ * returns the same tracker for the same store instance.
+ */
+export declare function getPendingWritesFor(store: object): PendingResponseWrites;
+//# sourceMappingURL=pending-writes.d.ts.map

package/dist/pending-writes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-writes.d.ts","sourceRoot":"","sources":["../src/pending-writes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwGG;AAEH;;;;;;;GAOG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyC;IAEjE;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAkC;IAE3E;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CACjB;IAEZ;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAAM;IAElD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI;IA0ClF;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS;IAInD;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAWtD;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;IAI3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,GAAG,OAAO;IAyB/E;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;IAYpB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAqBnC,iEAAiE;IACjE,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;;;;;;;OAYG;IACH,IAAI,gBAAgB,IAAI,MAAM,CAG7B;IAED;;;;;;OAMG;IACH,IAAI,4BAA4B,IAAI,MAAM,CAEzC;CACF;AAYD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,qBAAqB,CAOxE"}