peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/services/loop/spec-service.js

@@ -0,0 +1,497 @@
+/**
+ * peaks-loop v3.0.0 — Slice E.1
+ *
+ * Spec-as-first-class CLI backing service. Reads / writes / lints
+ * `.peaks/_runtime/<sid>/loop/<rid>/spec.yaml` — the project-level
+ * (third-tier) spec origin per Slice A resolver (project → global →
+ * bundled). Authors may also pass an explicit file path to `peaks loop
+ * spec lint`.
+ *
+ * Spec schema (v1):
+ *   - evaluators[].kind (native EvaluatorKind)
+ *   - evaluators[].gate? (Gate id or built-in "Gate …" label)
+ *   - evaluators[].scope? (string)
+ *   - sla[].evaluator (must match an evaluator.kind above)
+ *   - sla[].maxScore (0..1; the floor above which the evaluator is
+ *     considered to have held its SLA)
+ *   - termination.strategy ("max-cycles" | "monotonic-violation" |
+ *     "manual")
+ *   - termination.maxCycles? (positive integer when strategy = max-cycles)
+ *
+ * Karpathy §2 Simplicity First: pure data + a single hand-rolled
+ * YAML parser inline; no new deps.
+ *
+ * File budget: ≤ 800 lines.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, isAbsolute } from 'node:path';
+/** Default termination strategy — wired by `peaks loop run` so a
+ *  spec.yaml produced by `loop spec bootstrap` actually drives the
+ *  loop driver. Previously the string was declared-and-validated but
+ *  never consumed (P0 in dogfood audit). */
+export const MONOTONIC_TERMINATION = 'monotonic-violation';
+/** Default max-cycles value (used when the strategy is `max-cycles`
+ *  and the spec doesn't pin a value). Mirrors the slice dispatch
+ *  prompt's `termination.maxCycles` default. */
+export const DEFAULT_MAX_CYCLES = 5;
+/** Resolve a `LoopSpec` from the project-level origin. Returns
+ *  `{kind:'missing'}` when no file exists. The CLI layer then chooses
+ *  to bootstrap a fresh spec or fail. */
+export function resolveLoopSpec(projectRoot, sid, rid) {
+    const path = join(projectRoot, '.peaks', '_runtime', sid, 'loop', rid, 'spec.yaml');
+    if (!existsSync(path))
+        return { origin: { kind: 'missing' }, spec: null };
+    const raw = readFileSync(path, 'utf8');
+    const spec = parseSpecYaml(raw, rid);
+    return { origin: { kind: 'project', path }, spec };
+}
+/** Build a spec from a structured object (so CLI callers can pass a
+ *  JSON-derived payload through to the writer). Pure, never throws.
+ *  Note: numeric range validation is the lint layer's responsibility;
+ *  `buildSpec` preserves raw values so out-of-range entries surface in
+ *  `lintLoopSpec` rather than being silently clamped. */
+export function buildSpec(input, expectedRid) {
+    const evaluators = Array.isArray(input.evaluators) ? input.evaluators.map((e) => ({
+        kind: typeof e.kind === 'string' ? e.kind : '',
+        ...(typeof e.gate === 'string' ? { gate: e.gate } : {}),
+        ...(typeof e.scope === 'string' ? { scope: e.scope } : {})
+    })) : [];
+    const sla = Array.isArray(input.sla) ? input.sla.map((s) => ({
+        evaluator: typeof s.evaluator === 'string' ? s.evaluator : '',
+        maxScore: typeof s.maxScore === 'number' && Number.isFinite(s.maxScore) ? s.maxScore : Number.NaN
+    })) : [];
+    const term = input.termination ?? { strategy: 'manual' };
+    const strategy = (term.strategy === 'max-cycles' || term.strategy === 'monotonic-violation' || term.strategy === 'manual') ? term.strategy : 'manual';
+    const termination = {
+        strategy,
+        ...(typeof term.maxCycles === 'number' && Number.isFinite(term.maxCycles) && term.maxCycles > 0 ? { maxCycles: Math.floor(term.maxCycles) } : {})
+    };
+    return {
+        schemaVersion: 1,
+        rid: expectedRid,
+        evaluators,
+        sla,
+        termination
+    };
+}
+/** Lint a LoopSpec — returns a report with semantic errors / warnings. */
+export function lintLoopSpec(spec) {
+    const errors = [];
+    const warnings = [];
+    if (spec.schemaVersion !== 1)
+        errors.push(`unsupported schemaVersion ${spec.schemaVersion} (expected 1)`);
+    if (!/^[a-z][a-z0-9-]*$/.test(spec.rid))
+        errors.push(`rid "${spec.rid}" must match /^[a-z][a-z0-9-]*$/`);
+    const seenKinds = new Set();
+    for (const ev of spec.evaluators) {
+        if (typeof ev.kind !== 'string' || ev.kind.length === 0) {
+            errors.push(`evaluator with empty kind`);
+            continue;
+        }
+        if (seenKinds.has(ev.kind))
+            warnings.push(`evaluator kind "${ev.kind}" duplicated`);
+        seenKinds.add(ev.kind);
+    }
+    const evalKinds = new Set(spec.evaluators.map((e) => e.kind));
+    for (const s of spec.sla) {
+        if (!evalKinds.has(s.evaluator))
+            errors.push(`sla.evaluator "${s.evaluator}" is not declared in evaluators[]`);
+        if (s.maxScore < 0 || s.maxScore > 1)
+            errors.push(`sla.maxScore for "${s.evaluator}" must be in [0,1] (got ${s.maxScore})`);
+    }
+    if (spec.termination.strategy === 'max-cycles' && (spec.termination.maxCycles === undefined || spec.termination.maxCycles < 1)) {
+        errors.push(`termination.strategy=max-cycles requires maxCycles ≥ 1`);
+    }
+    return {
+        ok: errors.length === 0,
+        errors,
+        warnings,
+        normalizedSpec: spec
+    };
+}
+/** Serialize a LoopSpec to a stable YAML representation. Pure. */
+export function serializeSpec(spec) {
+    const lines = [];
+    lines.push('---');
+    lines.push('schemaVersion: 1');
+    lines.push(`rid: ${spec.rid}`);
+    if (spec.evaluators.length === 0) {
+        lines.push('evaluators: []');
+    }
+    else {
+        lines.push('evaluators:');
+        for (const ev of spec.evaluators) {
+            const props = [`kind: ${ev.kind}`];
+            if (ev.gate !== undefined)
+                props.push(`gate: ${ev.gate}`);
+            if (ev.scope !== undefined)
+                props.push(`scope: ${ev.scope}`);
+            lines.push(`  - ${props.join(', ')}`);
+        }
+    }
+    if (spec.sla.length === 0) {
+        lines.push('sla: []');
+    }
+    else {
+        lines.push('sla:');
+        for (const s of spec.sla) {
+            lines.push(`  - evaluator: ${s.evaluator}, maxScore: ${s.maxScore}`);
+        }
+    }
+    lines.push('termination:');
+    lines.push(`  strategy: ${spec.termination.strategy}`);
+    if (spec.termination.maxCycles !== undefined) {
+        lines.push(`  maxCycles: ${spec.termination.maxCycles}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+/** Persist a LoopSpec to disk at the project-level path; ensures the
+ *  parent directory exists. Returns the resolved path. */
+export function persistSpec(projectRoot, sid, spec) {
+    const path = join(projectRoot, '.peaks', '_runtime', sid, 'loop', spec.rid, 'spec.yaml');
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, serializeSpec(spec), 'utf8');
+    return path;
+}
+/** Lint a spec file from an explicit path — used by `peaks loop spec
+ *  lint <file>`. Returns the lint report plus the parsed spec. */
+export function lintSpecFile(filePath, expectedRid) {
+    if (!existsSync(filePath)) {
+        return {
+            raw: '',
+            spec: null,
+            report: { ok: false, errors: [`spec file not found: ${filePath}`], warnings: [] }
+        };
+    }
+    const raw = readFileSync(filePath, 'utf8');
+    let rid = expectedRid ?? '';
+    if (rid === '') {
+        // Derive rid from the parent dir name (slice dir = rid).
+        const segments = filePath.split(/[\\\/]/);
+        const specDir = segments[segments.length - 2] ?? '';
+        rid = specDir.length > 0 ? specDir : 'spec';
+    }
+    try {
+        const spec = parseSpecYaml(raw, rid);
+        const report = lintLoopSpec(spec);
+        return { raw, spec, report };
+    }
+    catch (error) {
+        return {
+            raw,
+            spec: null,
+            report: { ok: false, errors: [`failed to parse spec yaml: ${error instanceof Error ? error.message : String(error)}`], warnings: [] }
+        };
+    }
+}
+// ─── minimal hand-rolled YAML parser ────────────────────────────────────
+/**
+ * Tiny subset of YAML: indented objects + nested arrays of inline objects.
+ * Mirrors the workflow yaml parser's shape, with two extensions:
+ *  - tolerates inline `{ key: value, key: value }` objects (used for
+ *    evaluator entries and termination.strategy/maxCycles), and
+ *  - accepts `- kind: foo, gate: bar, scope: baz` (inline objects on
+ *    array items).
+ *
+ * Karpathy §2: hand-rolled to avoid a new dep, same approach as
+ * `src/services/workflow/workflow-spec.ts`.
+ */
+export function parseSpecYaml(raw, expectedRid) {
+    if (typeof raw !== 'string' || raw.length === 0) {
+        throw new Error('spec yaml: input is empty');
+    }
+    // Tolerate `---` frontmatter.
+    const lines = raw.split(/\r?\n/).filter((l, idx) => !(idx === 0 && l.trim() === '---'));
+    const root = parseObjectBlock(lines, 0, 0).value;
+    return buildSpec(root, expectedRid);
+}
+function parseObjectBlock(lines, start, baseIndent) {
+    const obj = {};
+    let i = start;
+    for (; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (line.trim() === '' || line.trim().startsWith('#'))
+            continue;
+        const indent = leadingSpaces(line);
+        if (indent < baseIndent)
+            return { value: obj, next: i };
+        if (indent > baseIndent)
+            continue; // caller should escalate
+        const trimmed = line.trim();
+        if (!trimmed.includes(':'))
+            continue;
+        const parts = splitTopLevel(trimmed, ':');
+        const key = parts[0] ?? '';
+        const value = (parts[1] ?? '').trim();
+        // When `value` still contains a top-level `: ,` pattern, the line is
+        // an inline object whose first key is the same as `key` (e.g.
+        // `strategy: max-cycles, maxCycles: 3` →
+        // `{strategy: 'max-cycles', maxCycles: 3}`). Re-stitch the leading
+        // key so the inline-object parser can see the full kv list, then
+        // store the resulting flat object as `obj[key]`.
+        if (key.length > 0 && value.length > 0 && hasInlineObjectShape(value)) {
+            obj[key] = parseInlineObject(`${key}: ${value}`);
+            continue;
+        }
+        if (value === '' || value === '|' || value === '>') {
+            // Could be nested block.
+            const next = lines[i + 1] ?? '';
+            const nextIndent = leadingSpaces(next);
+            if (nextIndent > indent) {
+                if (next.trim().startsWith('- ')) {
+                    const arrRes = parseArrayBlock(lines, i + 1, nextIndent);
+                    obj[key] = arrRes.value;
+                    i = arrRes.next - 1;
+                    continue;
+                }
+                else {
+                    const objRes = parseObjectBlock(lines, i + 1, nextIndent);
+                    obj[key] = objRes.value;
+                    i = objRes.next - 1;
+                    continue;
+                }
+            }
+            obj[key] = value === '|' || value === '>' ? '' : null;
+            continue;
+        }
+        obj[key] = parseValueOrInlineObject(value);
+    }
+    return { value: obj, next: i };
+}
+/** Inspect the trimmed value — if it looks like an inline object
+ *  (`key: val, key: val`), parse as such; otherwise treat as scalar. */
+function hasInlineObjectShape(value) {
+    if (typeof value !== 'string')
+        return false;
+    const trimmed = value.trim();
+    if (trimmed === '' || trimmed.startsWith('[') || trimmed.startsWith('{'))
+        return false;
+    let topColon = -1;
+    let topComma = -1;
+    let depth = 0;
+    let inQuote = null;
+    for (let i = 0; i < trimmed.length; i++) {
+        const ch = trimmed[i];
+        if (inQuote !== null) {
+            if (ch === inQuote)
+                inQuote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            inQuote = ch;
+            continue;
+        }
+        if (ch === '[' || ch === '{')
+            depth++;
+        if (ch === ']' || ch === '}')
+            depth--;
+        if (depth !== 0)
+            continue;
+        if (ch === ':' && topColon === -1)
+            topColon = i;
+        if (ch === ',')
+            topComma = i;
+    }
+    return topColon !== -1 && topComma !== -1;
+}
+function parseValueOrInlineObject(value) {
+    if (typeof value !== 'string')
+        return value;
+    const trimmed = value.trim();
+    if (trimmed === '' || trimmed.startsWith('[') || trimmed.startsWith('{')) {
+        return parseScalar(trimmed);
+    }
+    let topColon = -1;
+    let topComma = -1;
+    let depth = 0;
+    let inQuote = null;
+    for (let i = 0; i < trimmed.length; i++) {
+        const ch = trimmed[i];
+        if (inQuote !== null) {
+            if (ch === inQuote)
+                inQuote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            inQuote = ch;
+            continue;
+        }
+        if (ch === '[' || ch === '{')
+            depth++;
+        if (ch === ']' || ch === '}')
+            depth--;
+        if (depth !== 0)
+            continue;
+        if (ch === ':' && topColon === -1)
+            topColon = i;
+        if (ch === ',')
+            topComma = i;
+    }
+    if (topColon !== -1 && topComma !== -1 && topComma > topColon) {
+        return parseInlineObject(trimmed);
+    }
+    return parseScalar(trimmed);
+}
+function parseArrayBlock(lines, start, baseIndent) {
+    const arr = [];
+    let i = start;
+    for (; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (line.trim() === '' || line.trim().startsWith('#'))
+            continue;
+        const indent = leadingSpaces(line);
+        if (indent < baseIndent)
+            return { value: arr, next: i };
+        if (indent > baseIndent)
+            continue; // tolerate noise
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('- '))
+            continue;
+        const item = trimmed.slice(2).trim();
+        if (item.startsWith('{') && item.endsWith('}')) {
+            const inner = item.slice(1, -1).trim();
+            arr.push(parseInlineObject(inner));
+            continue;
+        }
+        if (item.includes(':')) {
+            // Inline object on array item (e.g. `- kind: foo, gate: bar`).
+            const inline = parseInlineObject(item);
+            arr.push(inline);
+            continue;
+        }
+        arr.push(parseScalar(item));
+    }
+    return { value: arr, next: i };
+}
+function parseInlineObject(body) {
+    // Split on top-level commas (not commas inside quotes — our spec has none).
+    const obj = {};
+    const parts = splitCommas(body);
+    // When the first part has no `:` (e.g. `strategy: max-cycles, maxCycles: 3`
+    // — caller already split on the leading `:`), use the previous answer's
+    // accumulator to stitch it back together. In practice, just take the
+    // shape: <key>: <val>, <key>: <val>, ... Each part is `key: val`.
+    let lastKey = null;
+    for (const p of parts) {
+        const colon = p.indexOf(':');
+        if (colon === -1) {
+            if (lastKey !== null) {
+                // Continuation: concatenate to the previous value (rare).
+                const prev = obj[lastKey];
+                if (typeof prev === 'string')
+                    obj[lastKey] = `${prev}, ${p.trim()}`;
+                else if (typeof prev === 'number')
+                    obj[lastKey] = `${prev}${p.trim()}`;
+            }
+            continue;
+        }
+        const key = p.slice(0, colon).trim();
+        const val = p.slice(colon + 1).trim();
+        obj[key] = parseScalar(val);
+        lastKey = key;
+    }
+    return obj;
+}
+function splitCommas(s) {
+    const out = [];
+    let depth = 0;
+    let cur = '';
+    let inQuote = null;
+    for (const ch of s) {
+        if (inQuote !== null) {
+            cur += ch;
+            if (ch === inQuote)
+                inQuote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            inQuote = ch;
+            cur += ch;
+            continue;
+        }
+        if (ch === '[' || ch === '{')
+            depth++;
+        if (ch === ']' || ch === '}')
+            depth--;
+        if (ch === ',' && depth === 0) {
+            out.push(cur);
+            cur = '';
+            continue;
+        }
+        cur += ch;
+    }
+    if (cur.length > 0)
+        out.push(cur);
+    return out.map((x) => x.trim()).filter((x) => x.length > 0);
+}
+function splitTopLevel(s, sep) {
+    let depth = 0;
+    let inQuote = null;
+    const out = [];
+    let cur = '';
+    for (const ch of s) {
+        if (inQuote !== null) {
+            cur += ch;
+            if (ch === inQuote)
+                inQuote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            inQuote = ch;
+            cur += ch;
+            continue;
+        }
+        if (ch === '[' || ch === '{')
+            depth++;
+        if (ch === ']' || ch === '}')
+            depth--;
+        if (ch === sep && depth === 0) {
+            out.push(cur);
+            cur = '';
+            continue;
+        }
+        cur += ch;
+    }
+    if (cur.length > 0)
+        out.push(cur);
+    return out;
+}
+function leadingSpaces(line) {
+    let n = 0;
+    for (const ch of line) {
+        if (ch === ' ')
+            n++;
+        else
+            break;
+    }
+    return n;
+}
+function parseScalar(raw) {
+    if (raw === '')
+        return '';
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    if (raw === 'null' || raw === '~')
+        return null;
+    if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
+        return raw.slice(1, -1);
+    }
+    if (/^-?\d+$/.test(raw))
+        return parseInt(raw, 10);
+    if (/^-?\d+\.\d+$/.test(raw))
+        return parseFloat(raw);
+    return raw;
+}
+export function specPath(projectRoot, sid, rid) {
+    return join(projectRoot, '.peaks', '_runtime', sid, 'loop', rid, 'spec.yaml');
+}
+/** Force a path to be inside the project root — guards against the
+ *  `peaks loop spec lint <file>` flag accepting arbitrary paths. The
+ *  caller decides whether the resulting abs path is in-bounds. */
+export function pathIsInside(child, parent) {
+    const abs = isAbsolute(child) ? child : join(parent, child);
+    return abs.startsWith(parent);
+}

package/dist/services/memory/llm-reranker.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Slice Z-A (2.8.0) — LLM rerank service (Y2 architecture, zero new deps).
+ *
+ * Receives a fuzzy top-N candidate list (from `searchMemory` /
+ * `MemorySearchResult[]`) and asks an LLM to rerank them by relevance
+ * to the query. Returns the top-K in descending relevance.
+ *
+ * Architecture note (locked decision — see
+ * `.peaks/memory/2026-06-18-peaks-zvec-spike-proposal.md` §Y2):
+ *
+ *   - "Active IDE LLM" is a deliberate abstraction: peaks-loop itself
+ *     has NO direct LLM API key. The chat call is performed by the
+ *     active IDE (Claude Code / Trae / Cursor / Codex / ...) using
+ *     its own authentication chain.
+ *
+ *   - The current `IdeAdapter` interface has no `chat()` method —
+ *     `SubAgentDispatcher` returns IDE-private tool-call descriptors
+ *     (sub-agent dispatch, not direct chat). This service therefore
+ *     takes a `chat` function INJECTION at the call site. The default
+ *     is a no-op that fails-open (returns the original fuzzy order).
+ *
+ *   - This is a SPIKE artifact for Z-A. The real chat wiring (either
+ *     a new `IdeAdapter.chat()` method, or routing through
+ *     `SubAgentDispatcher` with a "rerank" role) is a Z-B prerequisite
+ *     and is tracked in the GO/NO-GO report at
+ *     `.peaks/memory/memory-search-y2-rerank-2026-06-19-decision.md`.
+ *
+ * Why this is split from `memory-search-service.ts`:
+ *
+ *   - The fuzzy kernel is pure + synchronous + 100% testable today.
+ *   - The rerank layer is async + IO-bound + 100% fallback. Keeping
+ *     it separate means the existing 2800+ fuzzy tests are untouched
+ *     and the new spike has its own test surface (per the Z-A
+ *     proposal's "不重写 memory-search-service.ts" red line).
+ *
+ * Why 4-bytes-per-token:
+ *
+ *   - `headroom-client.ts:60` already uses `BYTES_PER_TOKEN = 4` as
+ *     its rough English-text approximation. Reusing the same constant
+ *     keeps token estimates comparable across the headroom + rerank
+ *     pipelines in the AC-ZA-5 benchmark.
+ *
+ * Out of scope (YAGNI per Karpathy #2 Simplicity First):
+ *
+ *   - No cross-process cache (AC-ZA-6 deferred — only build if
+ *     AC-ZA-5 shows a hot path).
+ *   - No rerank-prompt optimization beyond the minimal JSON
+ *     output format.
+ *   - No integration with `memory-search-service.ts` (Z-A is a spike;
+ *     the wiring into `peaks memory search` is Z-B).
+ */
+import type { MemorySearchResult } from './memory-search-service.js';
+/**
+ * One chat message in OpenAI-compatible format. The rerank layer
+ * sends a single user-role message; `system` is reserved for Z-B
+ * once the prompt-engineering is solid.
+ */
+export interface RerankChatMessage {
+    readonly role: 'user' | 'system' | 'assistant';
+    readonly content: string;
+}
+/**
+ * Chat function injection. The caller is responsible for routing
+ * the messages to the active IDE's LLM (or a mock for tests). The
+ * function MUST resolve with the LLM's raw text response, or reject
+ * on timeout / network error. Markdown code fences are tolerated by
+ * `parseRerankResponse` and are NOT the chat function's job to strip.
+ */
+export type RerankChatFn = (messages: readonly RerankChatMessage[], signal: AbortSignal) => Promise<string>;
+/**
+ * Options for `rerank()`. All optional; defaults match the Z-A
+ * proposal's AC-ZA-4 (fuzzy top-10 → rerank → top-5).
+ */
+export interface RerankOptions {
+    /** Max candidates fed to the LLM. Default 10 (per AC-ZA-4). */
+    readonly topN?: number;
+    /** Max results returned to the caller. Default 5 (per AC-ZA-4). */
+    readonly topK?: number;
+    /** Per-call chat timeout in ms. Default 5000 (per AC-ZA-8 L2). */
+    readonly chatTimeoutMs?: number;
+    /** Chat function injection. Default fails-open (returns input order). */
+    readonly chat?: RerankChatFn;
+}
+/**
+ * Token accounting for a single rerank call. Exposed so the
+ * AC-ZA-5 benchmark can report per-pipeline cost.
+ */
+export interface RerankTokenUsage {
+    /** Tokens used to assemble the rerank prompt (query + candidates). */
+    readonly promptTokens: number;
+    /** Tokens the LLM emitted (estimated via length/4). */
+    readonly responseTokens: number;
+    readonly total: number;
+}
+/**
+ * Rerank result. Always returns a `topK` array (possibly the
+ * original fuzzy order if rerank failed / was skipped) and a
+ * `warning` describing any degradation. Never throws — the
+ * caller can always use `topK` as a safe drop-in for the
+ * fuzzy top-K.
+ */
+export interface RerankResult {
+    /** Final ordered list (length <= topK, never more than input). */
+    readonly topK: readonly MemorySearchResult[];
+    /** Token accounting (zeros when rerank was skipped). */
+    readonly tokens: RerankTokenUsage;
+    /** One of 'reranked' | 'parse-failed-fallback' | 'chat-failed-fallback'
+     *  | 'timeout-fallback' | 'skipped-no-chat-fn' | 'noop-empty-input'. */
+    readonly degradation: string;
+    /** Human-readable detail. null when degradation === 'reranked'. */
+    readonly warning: string | null;
+}
+/**
+ * Estimate token count for a string. `1 token ≈ 4 bytes` for English
+ * text — same approximation as `headroom-client.ts:60`.
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Build the rerank prompt. Pure function — no IO, no side effects.
+ * Trivially testable.
+ *
+ * Format (locked for Z-A; Z-B may tune):
+ *
+ *   Query: "<query>"
+ *
+ *   Rank the following <N> candidate memories by relevance to the
+ *   query. Return a JSON array of the candidate indices in
+ *   descending relevance. Return only the JSON — no prose, no
+ *   markdown.
+ *
+ *   Candidates:
+ *   [0] name-a — description-a…
+ *   [1] name-b — description-b…
+ *   ...
+ *
+ * The LLM is expected to return e.g. `[3, 0, 4, 1, 2]`. The
+ * output is parsed by `parseRerankResponse`.
+ */
+export declare function renderRerankPrompt(query: string, candidates: readonly MemorySearchResult[]): string;
+/**
+ * Parse the LLM's raw text response into an ordered list of
+ * candidate indices. Tolerates:
+ *
+ *   - Pure JSON arrays: `[3, 0, 4, 1, 2]`
+ *   - JSON wrapped in markdown code fences:
+ *       ```json
+ *       [3, 0, 4, 1, 2]
+ *       ```
+ *   - Whitespace and surrounding prose (best-effort: looks for the
+ *     first `[...]` block)
+ *
+ * Returns `null` on parse failure (caller falls back to original
+ * fuzzy order per AC-ZA-8 L3).
+ */
+export declare function parseRerankResponse(raw: string): readonly number[] | null;
+/**
+ * Apply a parsed index ordering to a candidate list. Indices that
+ * are out-of-range or duplicated are skipped (defensive). If the
+ * ordering covers fewer candidates than `topK`, the remaining
+ * slots are filled from the original fuzzy order.
+ */
+export declare function applyRerankOrder(candidates: readonly MemorySearchResult[], order: readonly number[], topK: number): MemorySearchResult[];
+/**
+ * The no-op chat function. Used when no real chat injection is
+ * available — the rerank layer fails-open and the caller gets
+ * the original fuzzy order.
+ */
+export declare const noopRerankChat: RerankChatFn;
+/**
+ * Run the LLM rerank. Always returns a result — never throws.
+ * The caller can use `topK` as a drop-in replacement for the
+ * fuzzy top-K regardless of degradation mode.
+ */
+export declare function rerank(query: string, candidates: readonly MemorySearchResult[], options?: RerankOptions): Promise<RerankResult>;