peaks-loop 3.0.0

package/dist/src/services/mut/types.js

@@ -0,0 +1,59 @@
+/**
+ * Per spec §4.2 验收审计 + §7 阶段二 — MutReportJson v1.0.
+ *
+ * Hard constraints:
+ *   H8 (audit trail hashable): sha256 + inputSig (chain to TACT.sig)
+ *   H6 (CLI裁决, not LLM): passed boolean is computed by CLI, not LLM
+ */
+import { z } from 'zod';
+export const WeakPatternSchema = z.enum([
+    'toBeDefined', 'toBeTruthy', 'toEqual-self', 'expect-anything', 'toBe-self',
+]);
+export const MutReportSchema = z.object({
+    version: z.literal('1.0'),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    generatedAt: z.string().datetime(),
+    inputSig: z.string().regex(/^[a-f0-9]{64}$/),
+    mutation: z.object({
+        tool: z.enum(['stryker', 'mutmut', 'go-mutesting']),
+        mutantsTotal: z.number().int().nonnegative(),
+        mutantsKilled: z.number().int().nonnegative(),
+        mutantsSurvived: z.number().int().nonnegative(),
+        mutantsTimeout: z.number().int().nonnegative(),
+        killRate: z.number().min(0).max(1),
+        byFile: z.array(z.object({
+            file: z.string(),
+            killRate: z.number().min(0).max(1),
+            survived: z.array(z.object({
+                line: z.number().int(),
+                mutation: z.string(),
+                survivedBecause: z.string(),
+            })),
+        })),
+    }),
+    assertions: z.object({
+        totalAssertions: z.number().int().nonnegative(),
+        weakAssertions: z.number().int().nonnegative(),
+        weakRate: z.number().min(0).max(1),
+        weakPatterns: z.array(z.object({
+            pattern: WeakPatternSchema,
+            count: z.number().int().nonnegative(),
+            examples: z.array(z.object({
+                file: z.string(),
+                line: z.number().int(),
+                code: z.string(),
+            })),
+        })),
+    }),
+    thresholds: z.object({
+        mutationKillRateMin: z.number().min(0).max(1),
+        weakAssertionRateMax: z.number().min(0).max(1),
+        passed: z.boolean(),
+    }),
+    followups: z.array(z.object({
+        file: z.string(),
+        issue: z.enum(['low_kill_rate', 'high_weak_assertions']),
+        severity: z.enum(['soft', 'hard']),
+        suggestion: z.string(),
+    })),
+});

package/dist/src/services/observability/aggregation.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Read-only aggregations over observability events.
+ *
+ * Slice B of v2.11.1. Pure functions over `readonly ObservabilityEvent[]`
+ * — the CLI layer reads events via `readObservabilityEvents` (or
+ * `listSessionDirsWithMetrics` for cross-session rollups) and passes
+ * them in. Tests pass synthetic events directly.
+ *
+ * Aggregations:
+ *   - `aggregateStatus(events)`        → AC-1
+ *   - `aggregateSlices(events)`        → AC-2
+ *   - `aggregateFanout(events)`        → AC-3
+ *   - `aggregateRepairCycles(events)`  → AC-4
+ *
+ * The dispatch / mode-gate / context / post-compact categories land
+ * in Slice C (more hooks); for Slice B only `slice-transition` events
+ * are emitted from the `peaks request transition` hook. Slice B
+ * builds the read-side surface so Slice C is purely additive.
+ */
+import { type ObservabilityEvent, type ObservabilitySubagentRole } from './observability-service.js';
+export type StatusAggregate = {
+    totalEvents: number;
+    totalSlices: number;
+    successCount: number;
+    failCount: number;
+    repairCyclePeak: number;
+    fanoutCostTotal: number;
+};
+export type SliceRollup = {
+    sliceRid: string;
+    transitions: number;
+    firstTs: string | null;
+    lastTs: string | null;
+    durationMs: number | null;
+    finalState: string | null;
+    fanoutCount: number;
+    repairCycleCount: number;
+    success: boolean;
+};
+export type FanoutBreakdown = {
+    total: number;
+    perRole: Record<ObservabilitySubagentRole, number>;
+};
+export type RepairCycleReport = {
+    totalCycles: number;
+    cap: number;
+    capHit: boolean;
+    capHitCount: number;
+    perSlice: Array<{
+        sliceRid: string;
+        cycleCount: number;
+    }>;
+};
+/** RD/QA repair-loop cap (matches the peaks-solo repair-loop contract). */
+export declare const REPAIR_CYCLE_CAP = 3;
+export declare function aggregateStatus(events: readonly ObservabilityEvent[]): StatusAggregate;
+export declare function aggregateSlices(events: readonly ObservabilityEvent[]): SliceRollup[];
+export declare function aggregateFanout(events: readonly ObservabilityEvent[]): FanoutBreakdown;
+export declare function aggregateRepairCycles(events: readonly ObservabilityEvent[]): RepairCycleReport;
+export type Period = 'day' | 'week' | 'month';
+export declare function periodStartIso(period: Period, now?: () => Date): string;
+export declare function filterByPeriod(events: readonly ObservabilityEvent[], period: Period, now?: () => Date): ObservabilityEvent[];
+export declare function readAllSessionEvents(projectRoot: string): ObservabilityEvent[];
+export declare function readSessionEvents(projectRoot: string, sessionId: string): ObservabilityEvent[];

package/dist/src/services/observability/aggregation.js

@@ -0,0 +1,217 @@
+/**
+ * Read-only aggregations over observability events.
+ *
+ * Slice B of v2.11.1. Pure functions over `readonly ObservabilityEvent[]`
+ * — the CLI layer reads events via `readObservabilityEvents` (or
+ * `listSessionDirsWithMetrics` for cross-session rollups) and passes
+ * them in. Tests pass synthetic events directly.
+ *
+ * Aggregations:
+ *   - `aggregateStatus(events)`        → AC-1
+ *   - `aggregateSlices(events)`        → AC-2
+ *   - `aggregateFanout(events)`        → AC-3
+ *   - `aggregateRepairCycles(events)`  → AC-4
+ *
+ * The dispatch / mode-gate / context / post-compact categories land
+ * in Slice C (more hooks); for Slice B only `slice-transition` events
+ * are emitted from the `peaks request transition` hook. Slice B
+ * builds the read-side surface so Slice C is purely additive.
+ */
+import { readObservabilityEvents } from './observability-service.js';
+import { listSessionDirsWithMetrics } from './jsonl-store.js';
+// Slice lifecycle terminal states. Anything not listed is in-flight
+// (draft / spec-locked / implemented / qa-handoff / running).
+const TERMINAL_HAPPY_STATES = new Set([
+    'handed-off',
+    'verdict-issued',
+    'impact-recorded',
+    'boundary-recorded'
+]);
+const TERMINAL_FAIL_STATES = new Set(['blocked']);
+/** RD/QA repair-loop cap (matches the peaks-solo repair-loop contract). */
+export const REPAIR_CYCLE_CAP = 3;
+// v2.12.0 fan-out collapse: see OBSERVABILITY_SUBAGENT_ROLES for the
+// rationale on why `security-reviewer` was dropped and `peaks-security-audit`
+// + `peaks-perf-audit` were added.
+const ZERO_FANOUT = {
+    'rd': 0,
+    'qa': 0,
+    'code-reviewer': 0,
+    'karpathy-reviewer': 0,
+    'peaks-security-audit': 0,
+    'peaks-perf-audit': 0
+};
+// ----- internal helpers -----
+function isSliceTransition(event) {
+    return event.category === 'slice-transition' && typeof event.sliceRid === 'string';
+}
+function artifactRole(event) {
+    const detail = event.detail;
+    return typeof detail.artifactRole === 'string' ? detail.artifactRole : '';
+}
+function transitionTo(event) {
+    const detail = event.detail;
+    return typeof detail.to === 'string' ? detail.to : null;
+}
+function durationMsBetween(firstTs, lastTs) {
+    const a = new Date(firstTs).getTime();
+    const b = new Date(lastTs).getTime();
+    if (!Number.isFinite(a) || !Number.isFinite(b)) {
+        return 0;
+    }
+    return Math.max(0, b - a);
+}
+// ----- per-slice rollup (shared by status + slices queries) -----
+function rollupSlices(events) {
+    const bySlice = new Map();
+    for (const event of events) {
+        if (!isSliceTransition(event))
+            continue;
+        const rid = event.sliceRid;
+        let rollup = bySlice.get(rid);
+        if (rollup === undefined) {
+            rollup = {
+                sliceRid: rid,
+                transitions: 0,
+                firstTs: null,
+                lastTs: null,
+                durationMs: null,
+                finalState: null,
+                fanoutCount: 0,
+                repairCycleCount: 0,
+                success: false
+            };
+            bySlice.set(rid, rollup);
+        }
+        rollup.transitions += 1;
+        if (rollup.firstTs === null || event.ts < rollup.firstTs)
+            rollup.firstTs = event.ts;
+        if (rollup.lastTs === null || event.ts > rollup.lastTs)
+            rollup.lastTs = event.ts;
+        const to = transitionTo(event);
+        if (to !== null)
+            rollup.finalState = to;
+    }
+    for (const rollup of bySlice.values()) {
+        if (rollup.finalState !== null && TERMINAL_HAPPY_STATES.has(rollup.finalState)) {
+            rollup.success = true;
+        }
+        if (rollup.firstTs !== null && rollup.lastTs !== null) {
+            rollup.durationMs = durationMsBetween(rollup.firstTs, rollup.lastTs);
+        }
+    }
+    return bySlice;
+}
+function computeRepairCyclesBySlice(events) {
+    // Repair cycle = each rd → qa transition within one slice (proxy for the
+    // RD→QA→RD loop). For each slice we count qa transitions that follow an
+    // rd transition. Multiple qa transitions on the same slice are capped by
+    // REPAIR_CYCLE_CAP at the report level — the per-slice count here is the
+    // raw observation count.
+    const cyclesBySlice = new Map();
+    for (const event of events) {
+        if (!isSliceTransition(event))
+            continue;
+        const rid = event.sliceRid;
+        const role = artifactRole(event);
+        if (role === 'qa') {
+            cyclesBySlice.set(rid, (cyclesBySlice.get(rid) ?? 0) + 1);
+        }
+    }
+    return cyclesBySlice;
+}
+// ----- public aggregations -----
+export function aggregateStatus(events) {
+    const bySlice = rollupSlices(events);
+    const cyclesBySlice = computeRepairCyclesBySlice(events);
+    let repairCyclePeak = 0;
+    for (const rollup of bySlice.values()) {
+        const cycles = cyclesBySlice.get(rollup.sliceRid) ?? 0;
+        rollup.repairCycleCount = cycles;
+        if (cycles > repairCyclePeak)
+            repairCyclePeak = cycles;
+    }
+    const successCount = Array.from(bySlice.values()).filter((r) => r.success).length;
+    const failCount = Array.from(bySlice.values()).filter((r) => r.finalState !== null && TERMINAL_FAIL_STATES.has(r.finalState)).length;
+    const fanoutCostTotal = events.filter((e) => e.category === 'dispatch').length;
+    return {
+        totalEvents: events.length,
+        totalSlices: bySlice.size,
+        successCount,
+        failCount,
+        repairCyclePeak,
+        fanoutCostTotal
+    };
+}
+export function aggregateSlices(events) {
+    const bySlice = rollupSlices(events);
+    const cyclesBySlice = computeRepairCyclesBySlice(events);
+    for (const rollup of bySlice.values()) {
+        rollup.repairCycleCount = cyclesBySlice.get(rollup.sliceRid) ?? 0;
+    }
+    return Array.from(bySlice.values()).sort((a, b) => a.sliceRid.localeCompare(b.sliceRid));
+}
+export function aggregateFanout(events) {
+    const perRole = { ...ZERO_FANOUT };
+    let total = 0;
+    for (const event of events) {
+        if (event.category !== 'dispatch')
+            continue;
+        if (event.role !== undefined && event.role in perRole) {
+            perRole[event.role] += 1;
+            total += 1;
+        }
+    }
+    return { total, perRole };
+}
+export function aggregateRepairCycles(events) {
+    const cyclesBySlice = computeRepairCyclesBySlice(events);
+    const perSlice = Array.from(cyclesBySlice.entries())
+        .map(([sliceRid, cycleCount]) => ({ sliceRid, cycleCount }))
+        .sort((a, b) => a.sliceRid.localeCompare(b.sliceRid));
+    const totalCycles = perSlice.reduce((sum, row) => sum + row.cycleCount, 0);
+    const capHitCount = perSlice.filter((row) => row.cycleCount >= REPAIR_CYCLE_CAP).length;
+    return {
+        totalCycles,
+        cap: REPAIR_CYCLE_CAP,
+        capHit: capHitCount > 0,
+        capHitCount,
+        perSlice
+    };
+}
+export function periodStartIso(period, now = () => new Date()) {
+    const d = now();
+    if (period === 'day') {
+        d.setUTCHours(0, 0, 0, 0);
+        return d.toISOString();
+    }
+    if (period === 'week') {
+        d.setUTCHours(0, 0, 0, 0);
+        const day = d.getUTCDay();
+        const diff = (day + 6) % 7; // Monday = 0
+        d.setUTCDate(d.getUTCDate() - diff);
+        return d.toISOString();
+    }
+    d.setUTCDate(1);
+    d.setUTCHours(0, 0, 0, 0);
+    return d.toISOString();
+}
+export function filterByPeriod(events, period, now) {
+    const start = periodStartIso(period, now);
+    return events.filter((e) => e.ts >= start);
+}
+// ----- event-source helpers (CLI calls these; tests use pure functions) -----
+export function readAllSessionEvents(projectRoot) {
+    const sessions = listSessionDirsWithMetrics(projectRoot);
+    const all = [];
+    for (const { sessionId } of sessions) {
+        for (const event of readObservabilityEvents(projectRoot, sessionId)) {
+            all.push(event);
+        }
+    }
+    all.sort((a, b) => a.ts.localeCompare(b.ts));
+    return all;
+}
+export function readSessionEvents(projectRoot, sessionId) {
+    return readObservabilityEvents(projectRoot, sessionId);
+}

package/dist/src/services/observability/jsonl-store.d.ts

@@ -0,0 +1,59 @@
+/**
+ * JSONL append-only store for observability events.
+ *
+ * Slice A of v2.11.1 (slice topology observability). Pure file I/O —
+ * no schema knowledge lives here. Schema/validation lives in
+ * `observability-service.ts`.
+ *
+ * Layout: `.peaks/_runtime/<sessionId>/metrics/slices.jsonl` — one file
+ * per session, append-only. Mtime-based cross-session prune keeps at
+ * most `MAX_METRICS_FILES` files in the repo (mirrors the
+ * `peaks session checkpoint` contract).
+ *
+ * Write path is fire-and-forget: errors (disk full, permission
+ * denied, ENOENT mid-write) are swallowed silently per PRD Q4
+ * (full-auto must never fail-loud on observability).
+ */
+export declare const METRICS_DIR = "metrics";
+export declare const METRICS_FILENAME = "slices.jsonl";
+export declare const MAX_METRICS_FILES = 10;
+/** Absolute path to a session's metrics JSONL file. */
+export declare function metricsFilePath(projectRoot: string, sessionId: string): string;
+/** Absolute path to a session's metrics directory. */
+export declare function metricsDirPath(projectRoot: string, sessionId: string): string;
+/**
+ * Append one line to the session's metrics JSONL file. Creates the
+ * directory tree on demand. Returns true on success, false on any
+ * error (the caller MUST treat false as "drop silently" per Q4).
+ */
+export declare function appendMetricLine(projectRoot: string, sessionId: string, line: string): boolean;
+/**
+ * Read all non-empty lines from a session's metrics JSONL file.
+ * Returns [] when the file does not exist. Does NOT parse — callers
+ * decide what counts as valid (see `observability-service.ts`
+ * `readObservabilityEvents` for the schema-aware reader).
+ */
+export declare function readMetricLines(projectRoot: string, sessionId: string): string[];
+export type SessionMetricsEntry = {
+    sessionId: string;
+    mtimeMs: number;
+    path: string;
+};
+/**
+ * List every session that currently has a metrics JSONL on disk,
+ * paired with its mtime. Ordered by sessionId for determinism; the
+ * caller decides mtime ordering (see `pruneMetricsFiles`).
+ */
+export declare function listSessionDirsWithMetrics(projectRoot: string): SessionMetricsEntry[];
+/**
+ * Prune the metrics files across all sessions, retaining at most
+ * `MAX_METRICS_FILES` by mtime (newest kept). Returns the list of
+ * removed absolute paths. Best-effort: a failed removal is silently
+ * skipped (matches Q4 fire-and-forget contract).
+ */
+export declare function pruneMetricsFiles(projectRoot: string): string[];
+export declare const JSONL_STORE_CONSTANTS: {
+    readonly METRICS_DIR: "metrics";
+    readonly METRICS_FILENAME: "slices.jsonl";
+    readonly MAX_METRICS_FILES: 10;
+};

package/dist/src/services/observability/jsonl-store.js

@@ -0,0 +1,120 @@
+/**
+ * JSONL append-only store for observability events.
+ *
+ * Slice A of v2.11.1 (slice topology observability). Pure file I/O —
+ * no schema knowledge lives here. Schema/validation lives in
+ * `observability-service.ts`.
+ *
+ * Layout: `.peaks/_runtime/<sessionId>/metrics/slices.jsonl` — one file
+ * per session, append-only. Mtime-based cross-session prune keeps at
+ * most `MAX_METRICS_FILES` files in the repo (mirrors the
+ * `peaks session checkpoint` contract).
+ *
+ * Write path is fire-and-forget: errors (disk full, permission
+ * denied, ENOENT mid-write) are swallowed silently per PRD Q4
+ * (full-auto must never fail-loud on observability).
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { getSessionDir } from '../session/getSessionDir.js';
+export const METRICS_DIR = 'metrics';
+export const METRICS_FILENAME = 'slices.jsonl';
+export const MAX_METRICS_FILES = 10;
+/** Absolute path to a session's metrics JSONL file. */
+export function metricsFilePath(projectRoot, sessionId) {
+    return join(getSessionDir(projectRoot, sessionId), METRICS_DIR, METRICS_FILENAME);
+}
+/** Absolute path to a session's metrics directory. */
+export function metricsDirPath(projectRoot, sessionId) {
+    return join(getSessionDir(projectRoot, sessionId), METRICS_DIR);
+}
+/**
+ * Append one line to the session's metrics JSONL file. Creates the
+ * directory tree on demand. Returns true on success, false on any
+ * error (the caller MUST treat false as "drop silently" per Q4).
+ */
+export function appendMetricLine(projectRoot, sessionId, line) {
+    try {
+        const dir = metricsDirPath(projectRoot, sessionId);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        appendFileSync(metricsFilePath(projectRoot, sessionId), line + '\n', 'utf8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read all non-empty lines from a session's metrics JSONL file.
+ * Returns [] when the file does not exist. Does NOT parse — callers
+ * decide what counts as valid (see `observability-service.ts`
+ * `readObservabilityEvents` for the schema-aware reader).
+ */
+export function readMetricLines(projectRoot, sessionId) {
+    const path = metricsFilePath(projectRoot, sessionId);
+    if (!existsSync(path)) {
+        return [];
+    }
+    const raw = readFileSync(path, 'utf8');
+    return raw.split(/\r?\n/).filter((line) => line.length > 0);
+}
+/**
+ * List every session that currently has a metrics JSONL on disk,
+ * paired with its mtime. Ordered by sessionId for determinism; the
+ * caller decides mtime ordering (see `pruneMetricsFiles`).
+ */
+export function listSessionDirsWithMetrics(projectRoot) {
+    const runtimeRoot = join(projectRoot, '.peaks', '_runtime');
+    if (!existsSync(runtimeRoot)) {
+        return [];
+    }
+    const out = [];
+    for (const entry of readdirSync(runtimeRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const path = metricsFilePath(projectRoot, entry.name);
+        if (!existsSync(path)) {
+            continue;
+        }
+        out.push({
+            sessionId: entry.name,
+            mtimeMs: statSync(path).mtimeMs,
+            path
+        });
+    }
+    out.sort((a, b) => a.sessionId.localeCompare(b.sessionId));
+    return out;
+}
+/**
+ * Prune the metrics files across all sessions, retaining at most
+ * `MAX_METRICS_FILES` by mtime (newest kept). Returns the list of
+ * removed absolute paths. Best-effort: a failed removal is silently
+ * skipped (matches Q4 fire-and-forget contract).
+ */
+export function pruneMetricsFiles(projectRoot) {
+    const all = listSessionDirsWithMetrics(projectRoot);
+    if (all.length <= MAX_METRICS_FILES) {
+        return [];
+    }
+    all.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    const toRemove = all.slice(MAX_METRICS_FILES);
+    const removed = [];
+    for (const { path } of toRemove) {
+        try {
+            rmSync(path, { force: true });
+            removed.push(path);
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // best-effort: do not throw out of prune
+        }
+    }
+    return removed;
+}
+export const JSONL_STORE_CONSTANTS = {
+    METRICS_DIR,
+    METRICS_FILENAME,
+    MAX_METRICS_FILES
+};

package/dist/src/services/observability/observability-service.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Slice topology observability — schema + emit (Slice A of v2.11.1).
+ *
+ * Public surface:
+ *   - `emitObservabilityEvent(event, options)` — fire-and-forget write
+ *     to `.peaks/_runtime/<event.sessionId>/metrics/slices.jsonl`.
+ *   - `readObservabilityEvents(projectRoot, sessionId)` — schema-aware
+ *     reader that skips malformed lines and unknown schema versions
+ *     (per PRD Q3 forward-compat).
+ *
+ * Schema-versioned (schemaVersion: 1). The zod schema is the source of
+ * truth for the wire format. `ts` and `sessionId` are required; the
+ * caller is responsible for passing them (so each hook site has a
+ * canonical session binding even when run in a sub-agent).
+ *
+ * Per PRD Q4, `emit` MUST NEVER throw or fail-loud. All error paths
+ * collapse to `written: false` with a `reason` string so the caller can
+ * log if it wants — but the calling hook site itself swallows the
+ * result (fire-and-forget by convention).
+ */
+import { z } from 'zod';
+export declare const OBSERVABILITY_SCHEMA_VERSION: 1;
+export declare const OBSERVABILITY_CATEGORIES: readonly ["slice-transition", "dispatch", "checkpoint", "mode-gate", "context-trigger", "post-compact"];
+export type ObservabilityCategory = typeof OBSERVABILITY_CATEGORIES[number];
+export declare const OBSERVABILITY_SUBAGENT_ROLES: readonly ["rd", "qa", "code-reviewer", "karpathy-reviewer", "peaks-security-audit", "peaks-perf-audit"];
+export type ObservabilitySubagentRole = typeof OBSERVABILITY_SUBAGENT_ROLES[number];
+export declare const ObservabilityEventSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    ts: z.ZodString;
+    sessionId: z.ZodString;
+    category: z.ZodEnum<["slice-transition", "dispatch", "checkpoint", "mode-gate", "context-trigger", "post-compact"]>;
+    sliceRid: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodEnum<["rd", "qa", "code-reviewer", "karpathy-reviewer", "peaks-security-audit", "peaks-perf-audit"]>>;
+    detail: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string;
+    schemaVersion: 1;
+    ts: string;
+    category: "slice-transition" | "dispatch" | "checkpoint" | "mode-gate" | "context-trigger" | "post-compact";
+    detail: Record<string, unknown>;
+    role?: "qa" | "rd" | "code-reviewer" | "karpathy-reviewer" | "peaks-security-audit" | "peaks-perf-audit" | undefined;
+    sliceRid?: string | undefined;
+}, {
+    sessionId: string;
+    schemaVersion: 1;
+    ts: string;
+    category: "slice-transition" | "dispatch" | "checkpoint" | "mode-gate" | "context-trigger" | "post-compact";
+    detail: Record<string, unknown>;
+    role?: "qa" | "rd" | "code-reviewer" | "karpathy-reviewer" | "peaks-security-audit" | "peaks-perf-audit" | undefined;
+    sliceRid?: string | undefined;
+}>;
+export type ObservabilityEvent = z.infer<typeof ObservabilityEventSchema>;
+export type EmitOptions = {
+    /** Absolute path to the project root (where `.peaks/_runtime/` lives). */
+    projectRoot: string;
+};
+export type EmitFailureReason = 'invalid-schema' | 'write-failed';
+export type EmitResult = {
+    /** True when the JSONL line was appended; false on any error path. */
+    written: boolean;
+    /** Absolute path to the metrics file the event was written to (or would be). */
+    path: string;
+    /** Set only when `written` is false. */
+    reason?: EmitFailureReason;
+};
+/**
+ * Append a single observability event to the session's JSONL metrics
+ * file. Synchronous (small append, sub-ms in practice) and
+ * fire-and-forget by construction — the caller never awaits, and the
+ * function never throws.
+ *
+ * On success, also triggers the cross-session prune
+ * (`pruneMetricsFiles`). The prune is best-effort and cheap when the
+ * session count is below `MAX_METRICS_FILES`.
+ */
+export declare function emitObservabilityEvent(event: ObservabilityEvent, options: EmitOptions): EmitResult;
+/**
+ * Read all events from a session's metrics file, skipping malformed
+ * lines and any record whose `schemaVersion` does not match the
+ * current `OBSERVABILITY_SCHEMA_VERSION` (forward-compat per Q3).
+ *
+ * Returns [] when the session has no metrics file yet.
+ */
+export declare function readObservabilityEvents(projectRoot: string, sessionId: string): ObservabilityEvent[];
+/**
+ * True when the candidate record validates against the current
+ * schema (re-exported as a convenience for callers that already have
+ * parsed JSON and want to skip forward-compat records).
+ */
+export declare function isCurrentSchemaVersion(record: unknown): record is ObservabilityEvent;
+export declare const OBSERVABILITY_CONSTANTS: {
+    readonly SCHEMA_VERSION: 1;
+    readonly CATEGORIES: readonly ["slice-transition", "dispatch", "checkpoint", "mode-gate", "context-trigger", "post-compact"];
+    readonly SUBAGENT_ROLES: readonly ["rd", "qa", "code-reviewer", "karpathy-reviewer", "peaks-security-audit", "peaks-perf-audit"];
+};