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

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

@@ -1,400 +0,0 @@
-/**
- * peaks-loop v3.0.0 — Slice F (P0)
- *
- * Real closed-loop driver for `peaks loop run <rid>`. Previously the
- * `monotonic-violation` strategy was declared-and-validated but never
- * consumed (dogfood audit finding #2). This module makes the strategy
- * load-bearing: it reads `.peaks/_runtime/<sid>/loop/<rid>/spec.yaml`,
- * walks each `evaluators[].kind` in order via `dispatchEvaluator`,
- * captures a score row, persists the current cycle to disk, runs the
- * monotonic guard against the prior cycle, and decides whether to
- * continue / abort based on `termination.strategy`.
- *
- * Strategy semantics:
- *  - `monotonic-violation` (default): abort on MONOTONICITY_VIOLATION.
- *  - `max-cycles`: run exactly `termination.maxCycles` (default 5)
- *    cycles, aborting on any violation along the way.
- *  - `manual`: run exactly one cycle and exit 0; further cycles are
- *    the operator's responsibility.
- *  - anything else: `UNKNOWN_TERMINATION_STRATEGY`.
- *
- * Karpathy §2 Simplicity First: no new deps. Pure-data + JSON to
- * disk. The single in-process lock flag prevents two concurrent
- * `peaks loop run` calls (same sid+rid) from corrupting the cycle
- * index; cross-process locking is out of scope per the dispatch
- * prompt.
- *
- * File budget: ≤ 800 lines.
- */
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { resolveLoopSpec, lintLoopSpec, specPath, MONOTONIC_TERMINATION, DEFAULT_MAX_CYCLES } from './spec-service.js';
-import { dispatchEvaluator } from './evaluator-dispatcher.js';
-import { checkMonotonicImprovement, toScoreRow, DEFAULT_MONOTONIC_THRESHOLD } from './monotonic-guard.js';
-import { nextCycleIndex, sliceDir } from './monotonic-runner.js';
-import { findProjectRoot } from '../config/config-safety.js';
-function classifyFsError(err) {
-    const code = err?.code;
-    if (code === 'ENOENT')
-        return 'NOT_FOUND';
-    return 'IO_ERROR';
-}
-const ALLOWED_EVALUATOR_KINDS = new Set([
-    'karpathy',
-    'code-review',
-    'security-review',
-    'perf-baseline',
-    'verdict-aggregate',
-    'monotonic-improvement',
-    'impact-scan',
-    'smoke-run',
-    'canary-watch'
-]);
-/** In-process lock registry. Test seam: cleared by `_clearRunLocks()`. */
-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() {
-    RUN_LOCKS.clear();
-}
-function lockKey(sid, rid) {
-    return `${sid}::${rid}`;
-}
-/** Compose the cycle dir used for the writer (kept distinct from the
- *  slice dir so we can co-locate the per-cycle summary without
- *  overloading the monotonic-runner writer's `cycle-N.json`). */
-export function cyclesDir(projectRoot, sid, rid) {
-    return join(sliceDir(projectRoot, sid, rid), 'cycles');
-}
-/** Persist a single cycle's score row to the cycles dir as
- *  `cycle-<N>.json`. Returns the persisted path on success. */
-function persistCycleRecord(projectRoot, sid, rid, cycle, rows) {
-    const dir = cyclesDir(projectRoot, sid, rid);
-    const mkdir = (() => {
-        try {
-            mkdirSync(dir, { recursive: true });
-            return { ok: true, value: undefined };
-        }
-        catch (err) {
-            return { ok: false, reason: classifyFsError(err) };
-        }
-    })();
-    if (!mkdir.ok)
-        return null;
-    const path = join(dir, `cycle-${cycle}.json`);
-    const payload = JSON.stringify({
-        cycle,
-        rid,
-        sid,
-        persistedAt: new Date().toISOString(),
-        scores: rows
-    });
-    const writeFile = (() => {
-        try {
-            writeFileSync(path, payload, 'utf8');
-            return { ok: true, value: undefined };
-        }
-        catch (err) {
-            return { ok: false, reason: classifyFsError(err) };
-        }
-    })();
-    return writeFile.ok ? path : null;
-}
-/** Internal: build a CycleRecord from a (current, previous) pair. */
-function buildCycleRecord(cycle, rows, previous, threshold, persistedAt) {
-    const report = checkMonotonicImprovement(previous, { cycle, scores: rows }, { threshold });
-    return { cycle, rows, persistedAt, monotonicReport: report };
-}
-/** Default dispatcher — wraps the existing intra-process
- *  `dispatchEvaluator`. The driver deliberately shells out via the
- *  dispatcher's normal path so verdict shape stays byte-compatible
- *  with the rest of the loop primitive. */
-function defaultDispatch(kind, ctx, peaksBin) {
-    return dispatchEvaluator(kind, {
-        projectRoot: ctx.projectRoot,
-        rid: ctx.rid,
-        sessionId: ctx.sid,
-        ...(peaksBin !== undefined ? { peaksBin } : {})
-    });
-}
-/** Top-level entry point — `peaks loop run <rid>`.
- *
- *  Returns a `RunDriverResult` (the CLI layer maps `code → exit
- *  code` + printResult envelope). The function is intentionally
- *  non-throwing; per-cycle errors are captured as
- *  `code = EVALUATOR_THREW` but the loop continues to the next cycle
- *  so the caller sees a complete picture. */
-export function runLoop(options) {
-    // 1) Resolve + lint the spec.yaml.
-    const specPathStr = specPath(options.projectRoot, options.sid, options.rid);
-    if (!existsSync(specPathStr)) {
-        return emptyResult('SPEC_NOT_FOUND', `no spec.yaml at ${specPathStr}`, options);
-    }
-    const resolved = resolveLoopSpec(options.projectRoot, options.sid, options.rid);
-    if (resolved.spec === null) {
-        return emptyResult('SPEC_INVALID', `spec at ${specPathStr} is not parseable`, options);
-    }
-    const lint = lintLoopSpec(resolved.spec);
-    if (!lint.ok) {
-        return {
-            ...emptyResult('SPEC_INVALID', `spec at ${specPathStr} failed lint: ${lint.errors.join('; ')}`, options),
-            cycles: []
-        };
-    }
-    const spec = resolved.spec;
-    // 2) Resolve strategy. We use `string` so the literal 'unknown'
-    // remains in the narrowed type after the comparison — otherwise
-    // TS collapses the union with the spec's typed strategy.
-    const strategyRaw = options.strategyOverride ?? spec.termination.strategy;
-    const validStrategies = new Set([
-        'max-cycles',
-        MONOTONIC_TERMINATION,
-        'manual'
-    ]);
-    if (strategyRaw === 'unknown' || !validStrategies.has(strategyRaw)) {
-        return {
-            code: 'UNKNOWN_TERMINATION_STRATEGY',
-            ok: false,
-            message: `unknown termination.strategy "${strategyRaw}" (allowed: max-cycles, ${MONOTONIC_TERMINATION}, manual)`,
-            strategy: 'unknown',
-            maxCycles: 0,
-            cycles: [],
-            finalReport: null,
-            summary: { reachedMaxCycles: false, regressionCount: 0, totalCycles: 0 }
-        };
-    }
-    const strat = strategyRaw;
-    // `manual` runs a single cycle; `monotonic-violation` and
-    // `max-cycles` both honour `termination.maxCycles` (default
-    // DEFAULT_MAX_CYCLES). The dispatch prompt's `termination.maxCycles
-    // (默认 5)` applies to the default `monotonic-violation` strategy.
-    const maxCycles = strat === 'manual'
-        ? 1
-        : (options.maxCyclesOverride ?? spec.termination.maxCycles ?? DEFAULT_MAX_CYCLES);
-    // 3) Acquire the in-process lock.
-    const key = lockKey(options.sid, options.rid);
-    if (RUN_LOCKS.has(key)) {
-        return {
-            code: 'LOCKED',
-            ok: false,
-            message: `another peaks loop run is in progress for sid=${options.sid} rid=${options.rid}`,
-            strategy: strat,
-            maxCycles,
-            cycles: [],
-            finalReport: null,
-            summary: { reachedMaxCycles: false, regressionCount: 0, totalCycles: 0 }
-        };
-    }
-    RUN_LOCKS.set(key, true);
-    try {
-        return runLoopLocked(spec, strat, maxCycles, options);
-    }
-    finally {
-        RUN_LOCKS.delete(key);
-    }
-}
-function emptyResult(code, message, options) {
-    return {
-        code,
-        ok: false,
-        message,
-        strategy: 'unknown',
-        maxCycles: 0,
-        cycles: [],
-        finalReport: null,
-        summary: { reachedMaxCycles: false, regressionCount: 0, totalCycles: 0 }
-    };
-}
-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, {
-            projectRoot: options.projectRoot,
-            rid: options.rid,
-            sid: options.sid
-        }, options.peaksBin));
-    const cycleLimit = strategy === 'manual' ? 1 : maxCycles;
-    const evaluators = spec.evaluators.map((e) => e.kind);
-    const startCycle = nextCycleIndex(options.projectRoot, options.sid, options.rid);
-    const cycles = [];
-    let finalReport = null;
-    let aborted = false;
-    let abortCode = 'RUN_OK';
-    let abortMessage = '';
-    let regressionCount = 0;
-    let reachedMaxCycles = false;
-    for (let i = 0; i < cycleLimit; i++) {
-        const cycleNo = startCycle + i;
-        const rows = [];
-        for (const kind of evaluators) {
-            if (!ALLOWED_EVALUATOR_KINDS.has(kind)) {
-                // Skip unknown evaluator kinds — surface as a warn row so
-                // the cycle is still recorded.
-                const now = new Date().toISOString();
-                rows.push({
-                    evaluator: kind,
-                    score: 0.25,
-                    gateAction: 'warn',
-                    degraded: true,
-                    observedAt: now
-                });
-                continue;
-            }
-            try {
-                const env = dispatchFn(kind, {
-                    projectRoot: options.projectRoot,
-                    rid: options.rid,
-                    sid: options.sid
-                });
-                rows.push(toScoreRow(env.kind, env.gateAction, env.degraded, new Date().toISOString()));
-            }
-            catch {
-                // Per-evaluator failures must not crash the driver — degrade
-                // to warn, score 0.25, degraded=true. We track a flag for
-                // the summary so the user knows an evaluator failed.
-                const now = new Date().toISOString();
-                rows.push({
-                    evaluator: kind,
-                    score: 0.25,
-                    gateAction: 'warn',
-                    degraded: true,
-                    observedAt: now
-                });
-            }
-        }
-        // Read the previous cycle from in-memory state first, then fall
-        // back to disk (so that two successive `peaks loop run` calls
-        // see each other's persisted cycle).
-        const previousCycle = (() => {
-            if (cycles.length > 0) {
-                const last = cycles[cycles.length - 1];
-                return { cycle: last.cycle, scores: last.rows };
-            }
-            return loadCycleAt(options.projectRoot, options.sid, options.rid, cycleNo - 1);
-        })();
-        const persistedAt = persist
-            ? persistCycleRecord(options.projectRoot, options.sid, options.rid, cycleNo, rows)
-            : null;
-        const record = buildCycleRecord(cycleNo, rows, previousCycle, threshold, persistedAt);
-        cycles.push(record);
-        finalReport = record.monotonicReport;
-        if (record.monotonicReport.monotonicityViolation) {
-            regressionCount += record.monotonicReport.regressions.length;
-        }
-        if (record.monotonicReport.monotonicityViolation) {
-            // `monotonic-violation` strategy aborts on the first violation;
-            // `max-cycles` does too (the SLA is the loop). `manual` exits
-            // 0 with the violation recorded for the operator.
-            if (strategy === 'manual') {
-                abortCode = 'RUN_OK_REGRESSION';
-                abortMessage = `cycle ${cycleNo}: ${record.monotonicReport.reason}`;
-                aborted = true;
-                break;
-            }
-            abortCode = 'MONOTONICITY_VIOLATION';
-            abortMessage = `cycle ${cycleNo}: ${record.monotonicReport.reason}`;
-            aborted = true;
-            break;
-        }
-    }
-    if (!aborted) {
-        reachedMaxCycles = true;
-    }
-    const ok = abortCode === 'RUN_OK' || abortCode === 'RUN_OK_REGRESSION';
-    const summary = {
-        reachedMaxCycles,
-        regressionCount,
-        totalCycles: cycles.length
-    };
-    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)`),
-        strategy,
-        maxCycles,
-        cycles,
-        finalReport,
-        summary
-    };
-}
-/** Load the cycle-N.json row persisted by the previous run-driver
- *  invocation. Returns `null` when the file is missing. Used to
- *  compute `previousCycle` without re-reading the slice dir's
- *  `cycle-N.json` (the slice dir uses `cycle-N.json` for the
- *  monotonic-runner's prior cycle; the run-driver's own prior cycle
- *  is the *same* number — we read the matching row from the cycles
- *  subdir to keep the two writers isolated). */
-function loadCycleAt(projectRoot, sid, rid, n) {
-    if (n < 1)
-        return null;
-    const path = join(cyclesDir(projectRoot, sid, rid), `cycle-${n}.json`);
-    if (!existsSync(path)) {
-        // Fallback: read the slice-dir cycle-N.json (legacy monotonic-runner writes)
-        const legacy = join(sliceDir(projectRoot, sid, rid), `cycle-${n}.json`);
-        if (!existsSync(legacy))
-            return null;
-        return parseCycleFromPath(legacy, n);
-    }
-    return parseCycleFromPath(path, n);
-}
-function parseCycleFromPath(path, fallbackCycle) {
-    // Defer to monotonic-runner via a lazy require (the function is
-    // small and avoids leaking its internals).
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-    const fs = require('node:fs');
-    const readFile = (() => {
-        try {
-            return { ok: true, value: fs.readFileSync(path, 'utf8') };
-        }
-        catch (err) {
-            return { ok: false, reason: classifyFsError(err) };
-        }
-    })();
-    if (!readFile.ok)
-        return null;
-    const parse = (() => {
-        try {
-            return { ok: true, value: JSON.parse(readFile.value) };
-        }
-        catch {
-            return { ok: false, reason: 'PARSE_ERROR' };
-        }
-    })();
-    if (!parse.ok)
-        return null;
-    const parsed = parse.value;
-    if (parsed === null || typeof parsed !== 'object')
-        return null;
-    const obj = parsed;
-    const scores = Array.isArray(obj['scores']) ? obj['scores'] : [];
-    const rows = [];
-    for (const s of scores) {
-        if (s === null || typeof s !== 'object')
-            continue;
-        const r = s;
-        if (typeof r['evaluator'] !== 'string')
-            continue;
-        const gate = r['gateAction'];
-        if (gate !== 'pass' && gate !== 'warn' && gate !== 'block')
-            continue;
-        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),
-            gateAction: gate,
-            degraded: r['degraded'] === true,
-            observedAt
-        });
-    }
-    return { cycle: typeof obj['cycle'] === 'number' ? obj['cycle'] : fallbackCycle, scores: rows };
-}
-/** CLI helper: resolve the project root, sid, and rid from a
- *  `(project, session, rid)` triple. */
-export function resolveRunContext(opts) {
-    const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-    return { projectRoot, sid: opts.session, rid: opts.rid };
-}

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

@@ -1,90 +0,0 @@
-/** Spec origin — exposed as part of `peaks loop spec` output. */
-export type SpecOrigin = {
-    kind: 'project';
-    path: string;
-} | {
-    kind: 'global';
-    path: string;
-} | {
-    kind: 'missing';
-};
-export interface SpecEvaluatorEntry {
-    readonly kind: string;
-    readonly gate?: string;
-    readonly scope?: string;
-}
-export interface SpecSlaEntry {
-    readonly evaluator: string;
-    readonly maxScore: number;
-}
-export type SpecTerminationStrategy = 'max-cycles' | 'monotonic-violation' | 'manual';
-/** 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 declare const MONOTONIC_TERMINATION: SpecTerminationStrategy;
-/** 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 declare const DEFAULT_MAX_CYCLES = 5;
-export interface SpecTermination {
-    readonly strategy: SpecTerminationStrategy;
-    readonly maxCycles?: number;
-}
-export interface LoopSpec {
-    readonly schemaVersion: 1;
-    readonly rid: string;
-    readonly evaluators: readonly SpecEvaluatorEntry[];
-    readonly sla: readonly SpecSlaEntry[];
-    readonly termination: SpecTermination;
-}
-export interface SpecLintReport {
-    readonly ok: boolean;
-    readonly errors: readonly string[];
-    readonly warnings: readonly string[];
-    readonly normalizedSpec?: LoopSpec;
-}
-/** 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 declare function resolveLoopSpec(projectRoot: string, sid: string, rid: string): {
-    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. */
-export declare function lintLoopSpec(spec: LoopSpec): SpecLintReport;
-/** Serialize a LoopSpec to a stable YAML representation. Pure. */
-export declare function serializeSpec(spec: LoopSpec): string;
-/** Persist a LoopSpec to disk at the project-level path; ensures the
- *  parent directory exists. Returns the resolved path. */
-export declare function persistSpec(projectRoot: string, sid: string, spec: LoopSpec): string;
-/** Lint a spec file from an explicit path — used by `peaks loop spec
- *  lint <file>`. Returns the lint report plus the parsed spec. */
-export declare function lintSpecFile(filePath: string, expectedRid?: string): {
-    raw: string;
-    spec: LoopSpec | null;
-    report: SpecLintReport;
-};
-/**
- * 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 declare function parseSpecYaml(raw: string, expectedRid: string): LoopSpec;
-export declare function specPath(projectRoot: string, sid: string, rid: string): string;
-/** 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 declare function pathIsInside(child: string, parent: string): boolean;