peaks-loop 4.0.54 → 4.1.1

package/dist/services/loop/monotonic-runner.js

@@ -26,23 +26,7 @@ import { dispatchEvaluator } from './evaluator-dispatcher.js';
 import { checkMonotonicImprovement, toScoreRow, DEFAULT_MONOTONIC_THRESHOLD } from './monotonic-guard.js';
 import { appendMetricLine, readMetricLines } from '../observability/jsonl-store.js';
 import { findProjectRoot } from '../config/config-safety.js';
-function classifyFsError(err) {
-    const code = err?.code;
-    if (code === 'ENOENT')
-        return 'NOT_FOUND';
-    return 'IO_ERROR';
-}
-/** Tag for cycle lines in the jsonl-store. */
-const MONOTONIC_CYCLE_KIND = 'monotonic-cycle';
-/** Set of evaluator kinds the loop walker actually scores — keeps the
- *  guard surface tight (the verdict-aggregate is the cross-source merge
- *  and not a per-cycle input). */
-const WALKED_EVALUATORS = [
-    'karpathy',
-    'code-review',
-    'security-review',
-    'perf-baseline'
-];
+import { classifyFsError, MONOTONIC_CYCLE_KIND, WALKED_EVALUATORS } from './monotonic-runner-types.js';
 /** Resolve the slice dir — kept for API/BC (run-driver.ts uses it to
  *  derive `cyclesDir`). The monotonic-runner writer no longer writes
  *  here; the jsonl-store is the new persistence layer. */
@@ -55,8 +39,8 @@ export function sliceDir(projectRoot, sid, rid) {
  *  `.peaks/_sub_agents/<sid>/shared/` dir for cross-session signal.
  *  Returns `null` on any read error. */
 export function loadPreviousCycle(projectRoot, sid, rid) {
-    return loadMostRecentCycleFromJsonl(projectRoot, sid, rid)
-        ?? loadMostRecentCycleFromSubAgents(projectRoot, sid, rid);
+    return (loadMostRecentCycleFromJsonl(projectRoot, sid, rid) ??
+        loadMostRecentCycleFromSubAgents(projectRoot, sid, rid));
 }
 /** Scan the jsonl-store from tail backwards for the most recent
  *  `monotonic-cycle` line matching `rid`. Returns `null` when no
@@ -106,7 +90,13 @@ function parseScoreRows(raw) {
         const observedAt = typeof r['observedAt'] === 'string' ? r['observedAt'] : new Date(0).toISOString();
         out.push({
             evaluator: r['evaluator'],
-            score: typeof r['score'] === 'number' ? r['score'] : (gate === 'pass' ? 1.0 : gate === 'warn' ? 0.5 : 0.0),
+            score: typeof r['score'] === 'number'
+                ? r['score']
+                : gate === 'pass'
+                    ? 1.0
+                    : gate === 'warn'
+                        ? 0.5
+                        : 0.0,
             gateAction: gate,
             degraded: r['degraded'] === true,
             observedAt

package/dist/services/loop/run-driver.js

@@ -51,8 +51,8 @@ const ALLOWED_EVALUATOR_KINDS = new Set([
     'canary-watch'
 ]);
 /** In-process lock registry. Test seam: cleared by `_clearRunLocks()`. */
-const RUN_LOCKS = globalThis
-    .__PEAKS_RUN_LOCKS__ ?? new Map();
+const RUN_LOCKS = globalThis.__PEAKS_RUN_LOCKS__ ??
+    new Map();
 globalThis.__PEAKS_RUN_LOCKS__ = RUN_LOCKS;
 /** Test seam: clear in-process locks between test cases. */
 export function _clearRunLocks() {
@@ -209,8 +209,8 @@ function emptyResult(code, message, options) {
 function runLoopLocked(spec, strategy, maxCycles, options) {
     const threshold = options.threshold ?? DEFAULT_MONOTONIC_THRESHOLD;
     const persist = options.persist !== false;
-    const dispatchFn = options.dispatchOverride
-        ?? ((kind) => defaultDispatch(kind, {
+    const dispatchFn = options.dispatchOverride ??
+        ((kind) => defaultDispatch(kind, {
             projectRoot: options.projectRoot,
             rid: options.rid,
             sid: options.sid
@@ -311,9 +311,11 @@ function runLoopLocked(spec, strategy, maxCycles, options) {
     return {
         code: aborted ? abortCode : 'RUN_OK',
         ok,
-        message: aborted ? abortMessage : (strategy === 'manual'
-            ? `reached 1 cycle for manual strategy (no regressions observed)`
-            : `reached maxCycles ${cycleLimit} with ${regressionCount} regression(s)`),
+        message: aborted
+            ? abortMessage
+            : strategy === 'manual'
+                ? `reached 1 cycle for manual strategy (no regressions observed)`
+                : `reached maxCycles ${cycleLimit} with ${regressionCount} regression(s)`,
         strategy,
         maxCycles,
         cycles,
@@ -384,7 +386,13 @@ function parseCycleFromPath(path, fallbackCycle) {
         const observedAt = typeof r['observedAt'] === 'string' ? r['observedAt'] : new Date(0).toISOString();
         rows.push({
             evaluator: r['evaluator'],
-            score: typeof r['score'] === 'number' ? r['score'] : (gate === 'pass' ? 1.0 : gate === 'warn' ? 0.5 : 0.0),
+            score: typeof r['score'] === 'number'
+                ? r['score']
+                : gate === 'pass'
+                    ? 1.0
+                    : gate === 'warn'
+                        ? 0.5
+                        : 0.0,
             gateAction: gate,
             degraded: r['degraded'] === true,
             observedAt

package/dist/services/loop/spec-service.d.ts

@@ -51,11 +51,6 @@ export declare function resolveLoopSpec(projectRoot: string, sid: string, rid: s
     origin: SpecOrigin;
     spec: LoopSpec | null;
 };
-/** 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 declare function buildSpec(input: Partial<LoopSpec>, expectedRid: string): LoopSpec;
 /** Lint a LoopSpec — returns a report with semantic errors / warnings.
  *

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

@@ -25,6 +25,7 @@
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, isAbsolute } from 'node:path';
+import { isArray } from '../../shared/array-guards.js';
 /** 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
@@ -50,21 +51,53 @@ export function resolveLoopSpec(projectRoot, sid, rid) {
  *  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) => ({
+/** `evaluators[]` from a JSON-derived payload, or `[]` when absent / not an
+ *  array. Each entry is still inspected field-by-field; `kind` falls back to
+ *  `''` so `lintLoopSpec` reports it rather than this function throwing.
+ *
+ *  S10 (2026-09-20): extracted from `buildSpec` for two reasons. (1) The inline
+ *  form used `Array.isArray`, typed `arg is any[]`, which widened
+ *  `input.evaluators` — already `readonly SpecEvaluatorEntry[] | undefined` —
+ *  to `any[]` and made `e.kind` an `any` access; `isArray` does not widen.
+ *  (2) Keeping it inline would have cost `buildSpec` two extra branches, and its
+ *  complexity was already exactly at the rule's limit — extracting instead
+ *  lowers it. See `src/shared/array-guards.ts`. */
+function toEvaluatorEntries(value) {
+    if (value === undefined)
+        return [];
+    if (!isArray(value))
+        return [];
+    return value.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) => ({
+    }));
+}
+/** `sla[]` from a JSON-derived payload, or `[]` when absent / not an array. */
+function toSlaEntries(value) {
+    if (value === undefined)
+        return [];
+    if (!isArray(value))
+        return [];
+    return value.map((s) => ({
         evaluator: typeof s.evaluator === 'string' ? s.evaluator : '',
         maxScore: typeof s.maxScore === 'number' && Number.isFinite(s.maxScore) ? s.maxScore : Number.NaN
-    })) : [];
+    }));
+}
+export function buildSpec(input, expectedRid) {
+    const evaluators = toEvaluatorEntries(input.evaluators);
+    const sla = toSlaEntries(input.sla);
     const term = input.termination ?? { strategy: 'manual' };
-    const strategy = (term.strategy === 'max-cycles' || term.strategy === 'monotonic-violation' || term.strategy === 'manual') ? term.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) } : {})
+        ...(typeof term.maxCycles === 'number' && Number.isFinite(term.maxCycles) && term.maxCycles > 0
+            ? { maxCycles: Math.floor(term.maxCycles) }
+            : {})
     };
     return {
         schemaVersion: 1,
@@ -123,7 +156,8 @@ function validateSla(sla, evaluators, errors) {
     }
 }
 function validateTermination(termination, errors) {
-    if (termination.strategy === 'max-cycles' && (termination.maxCycles === undefined || termination.maxCycles < 1)) {
+    if (termination.strategy === 'max-cycles' &&
+        (termination.maxCycles === undefined || termination.maxCycles < 1)) {
         errors.push(`termination.strategy=max-cycles requires maxCycles ≥ 1`);
     }
 }
@@ -199,7 +233,13 @@ export function lintSpecFile(filePath, expectedRid) {
         return {
             raw,
             spec: null,
-            report: { ok: false, errors: [`failed to parse spec yaml: ${error instanceof Error ? error.message : String(error)}`], warnings: [] }
+            report: {
+                ok: false,
+                errors: [
+                    `failed to parse spec yaml: ${error instanceof Error ? error.message : String(error)}`
+                ],
+                warnings: []
+            }
         };
     }
 }

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

@@ -0,0 +1,108 @@
+/**
+ * Slice Z-A (2.8.0) — LLM rerank service: pure core.
+ *
+ * Extraction target for the `b1-filesplit-campaign` (wave 3, leaf
+ * `b1w3-c-memory`): the finding-free top-level surface of
+ * `llm-reranker.ts` (token/prompt constants, the public option/result types,
+ * and the synchronous pure helpers). `llm-reranker.ts` imports and re-exports
+ * everything here so its public API path is unchanged.
+ */
+import type { MemorySearchResult } from './memory-search-service.js';
+export declare const DEFAULT_TOP_N = 10;
+export declare const DEFAULT_TOP_K = 5;
+export declare const MAX_CANDIDATES = 30;
+export declare const DEFAULT_CHAT_TIMEOUT_MS = 5000;
+/**
+ * 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 (standard rough approximation).
+ */
+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;
+/**
+ * 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[];

package/dist/services/memory/llm-reranker-core.js

@@ -0,0 +1,105 @@
+/**
+ * Slice Z-A (2.8.0) — LLM rerank service: pure core.
+ *
+ * Extraction target for the `b1-filesplit-campaign` (wave 3, leaf
+ * `b1w3-c-memory`): the finding-free top-level surface of
+ * `llm-reranker.ts` (token/prompt constants, the public option/result types,
+ * and the synchronous pure helpers). `llm-reranker.ts` imports and re-exports
+ * everything here so its public API path is unchanged.
+ */
+// Approximate 1 token = 4 bytes for English text. Standard rough
+// approximation used across the pipeline (AC-ZA-5 benchmark).
+const BYTES_PER_TOKEN = 4;
+// Hard caps so a pathological query / 60-candidate list cannot blow
+// up the LLM prompt. These are conservative defaults; Z-B may tune.
+// Exported so `rerank()` (which stays in `llm-reranker.ts`) can read them.
+export const DEFAULT_TOP_N = 10;
+export const DEFAULT_TOP_K = 5;
+export const MAX_CANDIDATES = 30;
+const MAX_DESCRIPTION_CHARS = 240;
+export const DEFAULT_CHAT_TIMEOUT_MS = 5_000;
+/**
+ * Estimate token count for a string. `1 token ≈ 4 bytes` for English
+ * text (standard rough approximation).
+ */
+export function estimateTokens(text) {
+    return Math.ceil(Buffer.byteLength(text, 'utf8') / BYTES_PER_TOKEN);
+}
+/**
+ * Truncate a string to a maximum character count, appending an
+ * ellipsis marker when truncated. Used to keep the rerank prompt
+ * bounded when a candidate's description is unusually long.
+ */
+function truncateForPrompt(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    return `${text.slice(0, Math.max(0, maxChars - 1))}…`;
+}
+/**
+ * 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 function renderRerankPrompt(query, candidates) {
+    const blocks = candidates.map((c, i) => {
+        const desc = truncateForPrompt(c.description, MAX_DESCRIPTION_CHARS);
+        return `[${i}] ${c.name} — ${desc}`;
+    });
+    return [
+        `Query: "${query}"`,
+        '',
+        `Rank the following ${candidates.length} 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:',
+        ...blocks
+    ].join('\n');
+}
+/**
+ * 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 function applyRerankOrder(candidates, order, topK) {
+    const result = [];
+    const seen = new Set();
+    for (const idx of order) {
+        if (idx >= candidates.length)
+            continue;
+        if (seen.has(idx))
+            continue;
+        seen.add(idx);
+        const item = candidates[idx];
+        if (item === undefined)
+            continue;
+        result.push(item);
+        if (result.length >= topK)
+            return result;
+    }
+    for (let i = 0; i < candidates.length && result.length < topK; i += 1) {
+        if (seen.has(i))
+            continue;
+        const item = candidates[i];
+        if (item === undefined)
+            continue;
+        seen.add(i);
+        result.push(item);
+    }
+    return result;
+}

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

@@ -49,93 +49,9 @@
  *     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 (standard rough approximation).
- */
-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;
+import { type RerankChatFn, type RerankOptions, type RerankResult } from './llm-reranker-core.js';
+export { applyRerankOrder, estimateTokens, renderRerankPrompt } from './llm-reranker-core.js';
+export type { RerankChatFn, RerankChatMessage, RerankOptions, RerankResult, RerankTokenUsage } from './llm-reranker-core.js';
 /**
  * Parse the LLM's raw text response into an ordered list of
  * candidate indices. Tolerates:
@@ -152,13 +68,6 @@ export declare function renderRerankPrompt(query: string, candidates: readonly M
  * 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