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

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

@@ -1,497 +0,0 @@
-/**
- * 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/src/services/memory/llm-reranker.d.ts

@@ -1,174 +0,0 @@
-/**
- * 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>;