peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/slice/granularity-decider.d.ts

@@ -0,0 +1,37 @@
+/**
+ * GranularityDecider — pure function used by MultiPassOrchestrator to
+ * decide whether a WorkUnit should be subdivided further.
+ *
+ * No LLM dependency. Output is one of three branches:
+ *   - { subdivide: true }          — clearly over threshold, split now
+ *   - { subdivide: 'tie-break' }   — within 20% of threshold, defer to LLMArbitrator
+ *   - { subdivide: false }         — under threshold, stop subdividing
+ *
+ * The "tie-break" branch exists because large files (>80% of threshold)
+ * sometimes read like one cohesive unit; the orchestrator calls
+ * LLMArbitrator (which has project context) for that call.
+ */
+import type { WorkUnit } from './slice-decompose-types.js';
+export interface GranularityThresholds {
+    readonly maxFiles: number;
+    readonly maxLoc: number;
+}
+export type DeciderResult = {
+    readonly subdivide: true;
+    readonly reason: string;
+} | {
+    readonly subdivide: false;
+    readonly reason: string;
+} | {
+    readonly subdivide: 'tie-break';
+    readonly reason: string;
+};
+export declare const DEFAULT_THRESHOLDS: GranularityThresholds;
+/**
+ * Decide whether `wu` should be subdivided.
+ *
+ * Boundary semantics: `>` (strict). At the exact threshold (loc === maxLoc,
+ * files.length === maxFiles) the result is `subdivide: false`. This matches
+ * the spec: "threshold is exclusive; we only subdivide what is OVER it."
+ */
+export declare function shouldSubdivide(wu: WorkUnit, thresholds?: GranularityThresholds): DeciderResult;

package/dist/services/slice/granularity-decider.js

@@ -0,0 +1,40 @@
+/**
+ * GranularityDecider — pure function used by MultiPassOrchestrator to
+ * decide whether a WorkUnit should be subdivided further.
+ *
+ * No LLM dependency. Output is one of three branches:
+ *   - { subdivide: true }          — clearly over threshold, split now
+ *   - { subdivide: 'tie-break' }   — within 20% of threshold, defer to LLMArbitrator
+ *   - { subdivide: false }         — under threshold, stop subdividing
+ *
+ * The "tie-break" branch exists because large files (>80% of threshold)
+ * sometimes read like one cohesive unit; the orchestrator calls
+ * LLMArbitrator (which has project context) for that call.
+ */
+export const DEFAULT_THRESHOLDS = { maxFiles: 3, maxLoc: 400 };
+/**
+ * Decide whether `wu` should be subdivided.
+ *
+ * Boundary semantics: `>` (strict). At the exact threshold (loc === maxLoc,
+ * files.length === maxFiles) the result is `subdivide: false`. This matches
+ * the spec: "threshold is exclusive; we only subdivide what is OVER it."
+ */
+export function shouldSubdivide(wu, thresholds = DEFAULT_THRESHOLDS) {
+    const locExceeded = wu.loc > thresholds.maxLoc;
+    const filesExceeded = wu.files.length > thresholds.maxFiles;
+    if (locExceeded || filesExceeded) {
+        return {
+            subdivide: true,
+            reason: `wu ${wu.id}: loc=${wu.loc} files=${wu.files.length} exceeds threshold`,
+        };
+    }
+    const locBorderline = wu.loc > thresholds.maxLoc * 0.8;
+    const filesBorderline = wu.files.length > thresholds.maxFiles * 0.8;
+    if (locBorderline || filesBorderline) {
+        return {
+            subdivide: 'tie-break',
+            reason: `wu ${wu.id}: within 20% of threshold, needs LLM judgment`,
+        };
+    }
+    return { subdivide: false, reason: `wu ${wu.id}: under threshold` };
+}

package/dist/services/slice/llm-arbitrator.d.ts

@@ -0,0 +1,35 @@
+/**
+ * LLMArbitrator — the focused LLM 兜底 (fallback) path used by
+ * `CrossPassEdgeMerger` (W2 T7) when structural heuristics cannot
+ * decide whether a cross-pass edge is real.
+ *
+ * Contract:
+ *   - `arbitrate(prompt, opts)` is the only public entry point.
+ *   - Cache key is `sha256(prompt)`; cache file is `<cacheDir>/<hash>.json`.
+ *   - Cache hit short-circuits: llmRunner.call is NOT invoked.
+ *   - A module-level counter (`callsThisInvocation`) caps live LLM calls
+ *     per orchestrator invocation. When exhausted, the result is
+ *     `{ output: null, callId: 'budget-exhausted', tokens: null }`.
+ *   - Live calls are raced against `perCallTimeoutMs`; on timeout, return
+ *     `{ output: null, callId: 'timeout', tokens: null }`.
+ *   - On any other error, return `{ output: null, callId: 'error', tokens: null }`.
+ *   - `resetArbitratorBudget()` zeros the module counter so the orchestrator
+ *     can re-arm it for the next invocation.
+ */
+import type { LlmRunner } from '../audit/audit-goal-service.js';
+export interface ArbitratorOptions {
+    readonly cacheDir: string;
+    readonly maxCallsPerInvocation: number;
+    readonly perCallTimeoutMs: number;
+    readonly llmRunner: LlmRunner;
+}
+export interface ArbitrateResult {
+    readonly output: string | null;
+    readonly callId: string;
+    readonly tokens: {
+        input: number;
+        output: number;
+    } | null;
+}
+export declare function resetArbitratorBudget(): void;
+export declare function arbitrate(prompt: string, opts: ArbitratorOptions): Promise<ArbitrateResult>;

package/dist/services/slice/llm-arbitrator.js

@@ -0,0 +1,63 @@
+/**
+ * LLMArbitrator — the focused LLM 兜底 (fallback) path used by
+ * `CrossPassEdgeMerger` (W2 T7) when structural heuristics cannot
+ * decide whether a cross-pass edge is real.
+ *
+ * Contract:
+ *   - `arbitrate(prompt, opts)` is the only public entry point.
+ *   - Cache key is `sha256(prompt)`; cache file is `<cacheDir>/<hash>.json`.
+ *   - Cache hit short-circuits: llmRunner.call is NOT invoked.
+ *   - A module-level counter (`callsThisInvocation`) caps live LLM calls
+ *     per orchestrator invocation. When exhausted, the result is
+ *     `{ output: null, callId: 'budget-exhausted', tokens: null }`.
+ *   - Live calls are raced against `perCallTimeoutMs`; on timeout, return
+ *     `{ output: null, callId: 'timeout', tokens: null }`.
+ *   - On any other error, return `{ output: null, callId: 'error', tokens: null }`.
+ *   - `resetArbitratorBudget()` zeros the module counter so the orchestrator
+ *     can re-arm it for the next invocation.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const SYSTEM_PROMPT = 'You are a focused technical arbitrator.';
+let callsThisInvocation = 0;
+export function resetArbitratorBudget() {
+    callsThisInvocation = 0;
+}
+export async function arbitrate(prompt, opts) {
+    const promptHash = createHash('sha256').update(prompt).digest('hex');
+    const cacheFile = join(opts.cacheDir, `${promptHash}.json`);
+    if (existsSync(cacheFile)) {
+        const cached = JSON.parse(readFileSync(cacheFile, 'utf8'));
+        return {
+            output: cached.output,
+            callId: `cache:${promptHash.slice(0, 12)}`,
+            tokens: null
+        };
+    }
+    if (callsThisInvocation >= opts.maxCallsPerInvocation) {
+        return { output: null, callId: 'budget-exhausted', tokens: null };
+    }
+    try {
+        const result = await Promise.race([
+            opts.llmRunner.call(SYSTEM_PROMPT, prompt, { maxTokens: 1000 }),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), opts.perCallTimeoutMs))
+        ]);
+        callsThisInvocation++;
+        mkdirSync(opts.cacheDir, { recursive: true });
+        writeFileSync(cacheFile, JSON.stringify({ output: result.output, cachedAt: new Date().toISOString() }));
+        return {
+            output: result.output,
+            callId: `live:${promptHash.slice(0, 12)}`,
+            tokens: result.tokens
+        };
+    }
+    catch (err) {
+        const message = err.message;
+        return {
+            output: null,
+            callId: message === 'timeout' ? 'timeout' : 'error',
+            tokens: null
+        };
+    }
+}

package/dist/services/slice/multi-pass-orchestrator.d.ts

@@ -0,0 +1,67 @@
+/**
+ * MultiPassOrchestrator — Phase 2 of slice-topology-multipass (W2 T9).
+ *
+ * Top-level orchestrator that runs the existing 6-stage algorithm
+ * (`decomposeSlices`) at service-level and/or file-level granularity, then
+ * stitches the passes together with `merge` to produce a v2
+ * `DecompositionResultV2` with cross-pass edges.
+ *
+ * Granularity semantics:
+ *   - 'service': Pass 1 only. Each workUnit becomes a SliceV2 with
+ *                granularity='service' and parentSliceId=null.
+ *   - 'file':    Pass 2 only. `decomposeSlices` is called once on the full
+ *                scope (no parent subdivision). Each workUnit becomes a
+ *                SliceV2 with granularity='file' and parentSliceId=null.
+ *   - 'both':    Pass 1 + N Pass 2 (one per parent). Pass 2 runs for every
+ *                Pass 1 slice without decider filtering.
+ *   - 'auto':    Same as 'both' but Pass 2 only runs for parents where
+ *                `shouldSubdivide(wu).subdivide !== false` (both `true` and
+ *                `'tie-break'` qualify).
+ *
+ * Granularity-mapping approach (see pre-flight note in the task spec):
+ *   Approach 1 — pass-through with post-hoc filter. The 6-stage algorithm
+ *   (`decomposeSlices`) does NOT accept a `granularity` or `scopeFilter`
+ *   option, and the pre-flight note recommends NOT extending `DecomposeOptions`
+ *   (surgical change rule). We therefore:
+ *     1. Pass the full `opts` (including the orchestrator-only `granularity`
+ *        and `llmRunner` fields) through to `decomposeSlices`; the algorithm
+ *        ignores the extra fields.
+ *     2. Filter Pass 2 `result.workUnits` post-hoc so each Pass 2 result
+ *        only contains files inside the parent slice's file scope.
+ *
+ * Cross-pass edges are produced by `merge` whenever there are ≥2 passes.
+ * The merger handles both static detection (type-shares, fixture-shares,
+ * import-re-export — runs UNCONDITIONALLY) and the LLM fallback path (only
+ * when `opts.llmRunner` is provided). Without an llmRunner the orchestrator
+ * still gets statically-detected cross-pass edges; only `llmArbitrations`
+ * stays empty.
+ *
+ * @see ./slice-decompose-service.ts  — the 6-stage algorithm (reused as-is)
+ * @see ./granularity-decider.ts      — subdivide decision
+ * @see ./cross-pass-edge-merger.ts   — cross-pass edge detection
+ * @see ./llm-arbitrator.ts           — LLM fallback for cross-pass edges
+ * @see ./slice-topology-types.ts     — DecompositionResultV2, PassResult, etc.
+ */
+import type { LlmRunner } from '../audit/audit-goal-service.js';
+import type { DecomposeOptions } from './slice-decompose-types.js';
+import type { DecompositionResultV2 } from './slice-topology-types.js';
+export type Granularity = 'service' | 'file' | 'both' | 'auto';
+export interface MultiPassOptions extends DecomposeOptions {
+    /** Service-level vs file-level vs both. Defaults to `'both'`. */
+    readonly granularity?: Granularity;
+    /** Optional LLM runner; when present, cross-pass edges are computed via `merge`. */
+    readonly llmRunner?: LlmRunner;
+}
+/**
+ * Run the multi-pass decomposition algorithm and return a v2 result.
+ *
+ * 1. Reset the LLM arbitrator budget for this invocation.
+ * 2. Run Pass 1 (service-level) if granularity includes 'service'.
+ * 3. Run Pass 2 (file-level) — for every qualifying parent in 'both'/'auto',
+ *    or once on the full scope in 'file'-only mode.
+ * 4. Compute cross-pass edges via `merge` whenever there are ≥2 passes
+ *    (static detection runs unconditionally; LLM fallback only when an
+ *    llmRunner is supplied).
+ * 5. Return a `DecompositionResultV2` with `partial: false`.
+ */
+export declare function decompose(rid: string, prdMarkdown: string, projectRoot: string, opts?: MultiPassOptions): Promise<DecompositionResultV2>;

package/dist/services/slice/multi-pass-orchestrator.js

@@ -0,0 +1,225 @@
+/**
+ * MultiPassOrchestrator — Phase 2 of slice-topology-multipass (W2 T9).
+ *
+ * Top-level orchestrator that runs the existing 6-stage algorithm
+ * (`decomposeSlices`) at service-level and/or file-level granularity, then
+ * stitches the passes together with `merge` to produce a v2
+ * `DecompositionResultV2` with cross-pass edges.
+ *
+ * Granularity semantics:
+ *   - 'service': Pass 1 only. Each workUnit becomes a SliceV2 with
+ *                granularity='service' and parentSliceId=null.
+ *   - 'file':    Pass 2 only. `decomposeSlices` is called once on the full
+ *                scope (no parent subdivision). Each workUnit becomes a
+ *                SliceV2 with granularity='file' and parentSliceId=null.
+ *   - 'both':    Pass 1 + N Pass 2 (one per parent). Pass 2 runs for every
+ *                Pass 1 slice without decider filtering.
+ *   - 'auto':    Same as 'both' but Pass 2 only runs for parents where
+ *                `shouldSubdivide(wu).subdivide !== false` (both `true` and
+ *                `'tie-break'` qualify).
+ *
+ * Granularity-mapping approach (see pre-flight note in the task spec):
+ *   Approach 1 — pass-through with post-hoc filter. The 6-stage algorithm
+ *   (`decomposeSlices`) does NOT accept a `granularity` or `scopeFilter`
+ *   option, and the pre-flight note recommends NOT extending `DecomposeOptions`
+ *   (surgical change rule). We therefore:
+ *     1. Pass the full `opts` (including the orchestrator-only `granularity`
+ *        and `llmRunner` fields) through to `decomposeSlices`; the algorithm
+ *        ignores the extra fields.
+ *     2. Filter Pass 2 `result.workUnits` post-hoc so each Pass 2 result
+ *        only contains files inside the parent slice's file scope.
+ *
+ * Cross-pass edges are produced by `merge` whenever there are ≥2 passes.
+ * The merger handles both static detection (type-shares, fixture-shares,
+ * import-re-export — runs UNCONDITIONALLY) and the LLM fallback path (only
+ * when `opts.llmRunner` is provided). Without an llmRunner the orchestrator
+ * still gets statically-detected cross-pass edges; only `llmArbitrations`
+ * stays empty.
+ *
+ * @see ./slice-decompose-service.ts  — the 6-stage algorithm (reused as-is)
+ * @see ./granularity-decider.ts      — subdivide decision
+ * @see ./cross-pass-edge-merger.ts   — cross-pass edge detection
+ * @see ./llm-arbitrator.ts           — LLM fallback for cross-pass edges
+ * @see ./slice-topology-types.ts     — DecompositionResultV2, PassResult, etc.
+ */
+import { decomposeSlices } from './slice-decompose-service.js';
+import { resetArbitratorBudget } from './llm-arbitrator.js';
+import { shouldSubdivide } from './granularity-decider.js';
+import { merge } from './cross-pass-edge-merger.js';
+/**
+ * Run the multi-pass decomposition algorithm and return a v2 result.
+ *
+ * 1. Reset the LLM arbitrator budget for this invocation.
+ * 2. Run Pass 1 (service-level) if granularity includes 'service'.
+ * 3. Run Pass 2 (file-level) — for every qualifying parent in 'both'/'auto',
+ *    or once on the full scope in 'file'-only mode.
+ * 4. Compute cross-pass edges via `merge` whenever there are ≥2 passes
+ *    (static detection runs unconditionally; LLM fallback only when an
+ *    llmRunner is supplied).
+ * 5. Return a `DecompositionResultV2` with `partial: false`.
+ */
+export async function decompose(rid, prdMarkdown, projectRoot, opts = {}) {
+    resetArbitratorBudget();
+    const granularity = opts.granularity ?? 'both';
+    const wantService = granularity === 'service' || granularity === 'both' || granularity === 'auto';
+    const wantFile = granularity === 'file' || granularity === 'both' || granularity === 'auto';
+    const passes = [];
+    let codegraph = zeroCodegraph();
+    let understandAnything = zeroUnderstand();
+    let pass1WorkUnits = [];
+    if (wantService) {
+        const result1 = await decomposeSlices(rid, prdMarkdown, projectRoot, opts);
+        pass1WorkUnits = result1.workUnits;
+        passes.push({
+            passNumber: 1,
+            granularity: 'service',
+            slices: result1.workUnits.map((wu) => workUnitToSliceV2(wu, 'service')),
+            internalEdges: v1EdgesToV2(result1.dependencyDAG.edges)
+        });
+        codegraph = result1.codegraph;
+        understandAnything = result1.understandAnything;
+    }
+    if (wantFile) {
+        if (pass1WorkUnits.length > 0) {
+            // Per-parent subdivision. In 'auto' mode, only parents where
+            // shouldSubdivide is not explicitly false qualify.
+            const qualifyingParents = granularity === 'auto'
+                ? pass1WorkUnits.filter((wu) => shouldSubdivide(wu).subdivide !== false)
+                : pass1WorkUnits;
+            const pass2Results = await Promise.all(qualifyingParents.map(async (parent) => {
+                const result = await decomposeSlices(rid, prdMarkdown, projectRoot, opts);
+                const filtered = filterWorkUnitsByScope(result.workUnits, parent.files);
+                const pass2Slices = filtered.map((wu, i) => workUnitToSliceV2(wu, 'file', {
+                    id: `${parent.id}.${i + 1}`,
+                    parentSliceId: parent.id
+                }));
+                const pass2 = {
+                    passNumber: 2,
+                    granularity: 'file',
+                    slices: pass2Slices,
+                    internalEdges: v1EdgesToV2(result.dependencyDAG.edges)
+                };
+                return pass2;
+            }));
+            passes.push(...pass2Results);
+        }
+        else if (!wantService) {
+            // file-only mode: call decomposeSlices once on the full scope and
+            // treat the result as Pass 2 (no parent subdivision).
+            const result = await decomposeSlices(rid, prdMarkdown, projectRoot, opts);
+            const slices = result.workUnits.map((wu) => workUnitToSliceV2(wu, 'file'));
+            passes.push({
+                passNumber: 2,
+                granularity: 'file',
+                slices,
+                internalEdges: v1EdgesToV2(result.dependencyDAG.edges)
+            });
+            codegraph = result.codegraph;
+            understandAnything = result.understandAnything;
+        }
+    }
+    let crossPassEdges = [];
+    let llmArbitrations = [];
+    if (passes.length > 1) {
+        const mergeResult = await merge(passes, {
+            projectRoot,
+            ...(opts.llmRunner ? { llmRunner: opts.llmRunner } : {})
+        });
+        crossPassEdges = mergeResult.edges;
+        llmArbitrations = mergeResult.llmCalls.map(toLlmArbitration);
+    }
+    return {
+        schemaVersion: 'v2',
+        rid,
+        generatedAt: new Date().toISOString(),
+        passes,
+        crossPassEdges,
+        llmArbitrations,
+        codegraph,
+        understandAnything,
+        partial: false
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Convert a v1 `WorkUnit` into a v2 `SliceV2`. The `granularity` is supplied
+ * by the caller (per-pass) so it matches the pass's `PassResult.granularity`.
+ * `id` and `parentSliceId` default to the workUnit's own id and null
+ * (i.e. a Pass 1 slice). For Pass 2 children, the orchestrator supplies
+ * `${parent.id}.${i + 1}` as the new id and the parent's id as parent.
+ */
+function workUnitToSliceV2(wu, granularity, overrides = {}) {
+    return {
+        id: overrides.id ?? wu.id,
+        label: wu.label,
+        granularity,
+        files: wu.files,
+        loc: wu.loc,
+        parentSliceId: overrides.parentSliceId ?? null,
+        semanticAnchor: `file:${wu.filePath}`
+    };
+}
+/**
+ * Keep only workUnits that touch at least one file in the parent's scope.
+ * Used to scope Pass 2 results to their parent slice's file set, since the
+ * 6-stage algorithm does not accept a `scopeFilter` option.
+ */
+function filterWorkUnitsByScope(wus, scope) {
+    const scopeSet = new Set(scope);
+    return wus.filter((wu) => wu.files.some((f) => scopeSet.has(f)));
+}
+/**
+ * Map a v1 `DependencyEdge[]` (from the 6-stage algorithm's `dependencyDAG`)
+ * to v2 `InternalEdge[]`. The two kinds unions are identical
+ * (`'imports' | 'calls' | 'depends_on' | 'contains_flow' | 'flow_step'`), so
+ * `kind` is a direct pass-through. `confidence` collapses `isSemantic`
+ * (`true` → `'semantic'`, `false` → `'structural'`) to match the v2
+ * `EdgeConfidence` union.
+ */
+function v1EdgesToV2(v1Edges) {
+    return v1Edges.map((e) => ({
+        from: e.from,
+        to: e.to,
+        kind: e.kind,
+        weight: e.weight,
+        evidence: e.evidence,
+        confidence: e.isSemantic ? 'semantic' : 'structural'
+    }));
+}
+/**
+ * Pure shape pass-through from `MergeResult.llmCalls` to v2 `LlmArbitration`.
+ * The merger now populates `promptHash`/`input`/`output`/`confidence` itself;
+ * we just coalesce a possible `null` `tokens` to a zeroed pair to satisfy
+ * the non-nullable `LlmArbitration.tokens` contract.
+ */
+function toLlmArbitration(c) {
+    return {
+        callId: c.callId,
+        promptHash: c.promptHash,
+        input: c.input,
+        output: c.output,
+        confidence: c.confidence,
+        tokens: c.tokens ?? { input: 0, output: 0 }
+    };
+}
+function zeroCodegraph() {
+    return {
+        nodes: 0,
+        edges: 0,
+        dbMB: 0,
+        freshness: 'unindexed',
+        affectedCrossFile: false,
+        note: 'no decomposition run'
+    };
+}
+function zeroUnderstand() {
+    return {
+        kgNodes: 0,
+        kgEdges: 0,
+        available: false,
+        fallback: 'structural-only',
+        note: 'no decomposition run'
+    };
+}

package/dist/services/slice/schema-router.d.ts

@@ -0,0 +1,44 @@
+/**
+ * SchemaRouter — dual-read JSON router for `DecompositionResult` (v1/v2).
+ *
+ * v1 files (legacy, pre-Wave-1 slice decompose output) do NOT carry a
+ * `schemaVersion` field; v2 files always carry `schemaVersion: 'v2'`.
+ * The router reads the file, dispatches on the discriminator, and returns
+ * the parsed object typed as `DecompositionResult` or `DecompositionResultV2`.
+ *
+ * Why a router (and not a parse-on-write migration):
+ *  - v1 files may exist in user workspaces long after v2 ships; rewriting
+ *    them on read would force a write-back side-effect that callers don't
+ *    need (and breaks `peaks slice pick` which only needs the v1 fields).
+ *  - The discriminated return type lets callers narrow once at the boundary
+ *    (`schemaVersion === 'v2' ? handleV2(r) : handleV1(r)`) and stay typed
+ *    downstream.
+ *
+ * Unknown versions throw `UnknownSchemaVersionError` so callers can
+ * surface a clear migration hint instead of silently treating v3 as v1.
+ */
+import type { DecompositionResult } from './slice-decompose-types.js';
+import type { DecompositionResultV2 } from './slice-topology-types.js';
+/**
+ * Thrown by `readResult` when the JSON carries a `schemaVersion` value
+ * that is neither absent (v1) nor `'v2'`. The `code` is the stable
+ * machine-readable discriminator; downstream CLI surfaces should map it
+ * to the appropriate exit code.
+ */
+export declare class UnknownSchemaVersionError extends Error {
+    readonly code: "UNKNOWN_SCHEMA_VERSION";
+    constructor(message: string);
+}
+/**
+ * Read a decomposition-result JSON file and return it typed as either
+ * `DecompositionResult` (v1, no `schemaVersion` field) or
+ * `DecompositionResultV2` (`schemaVersion: 'v2'`).
+ *
+ * Throws `UnknownSchemaVersionError` for any other `schemaVersion` value.
+ */
+export declare function readResult(filePath: string): DecompositionResult | DecompositionResultV2;
+/**
+ * Serialize a v1 or v2 decomposition result to disk as pretty-printed JSON.
+ * The `schemaVersion` field (or its absence) is preserved as-is.
+ */
+export declare function writeResult(filePath: string, result: DecompositionResult | DecompositionResultV2): void;

package/dist/services/slice/schema-router.js

@@ -0,0 +1,61 @@
+/**
+ * SchemaRouter — dual-read JSON router for `DecompositionResult` (v1/v2).
+ *
+ * v1 files (legacy, pre-Wave-1 slice decompose output) do NOT carry a
+ * `schemaVersion` field; v2 files always carry `schemaVersion: 'v2'`.
+ * The router reads the file, dispatches on the discriminator, and returns
+ * the parsed object typed as `DecompositionResult` or `DecompositionResultV2`.
+ *
+ * Why a router (and not a parse-on-write migration):
+ *  - v1 files may exist in user workspaces long after v2 ships; rewriting
+ *    them on read would force a write-back side-effect that callers don't
+ *    need (and breaks `peaks slice pick` which only needs the v1 fields).
+ *  - The discriminated return type lets callers narrow once at the boundary
+ *    (`schemaVersion === 'v2' ? handleV2(r) : handleV1(r)`) and stay typed
+ *    downstream.
+ *
+ * Unknown versions throw `UnknownSchemaVersionError` so callers can
+ * surface a clear migration hint instead of silently treating v3 as v1.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+/**
+ * Thrown by `readResult` when the JSON carries a `schemaVersion` value
+ * that is neither absent (v1) nor `'v2'`. The `code` is the stable
+ * machine-readable discriminator; downstream CLI surfaces should map it
+ * to the appropriate exit code.
+ */
+export class UnknownSchemaVersionError extends Error {
+    code = 'UNKNOWN_SCHEMA_VERSION';
+    constructor(message) {
+        super(message);
+        this.name = 'UnknownSchemaVersionError';
+    }
+}
+/**
+ * Read a decomposition-result JSON file and return it typed as either
+ * `DecompositionResult` (v1, no `schemaVersion` field) or
+ * `DecompositionResultV2` (`schemaVersion: 'v2'`).
+ *
+ * Throws `UnknownSchemaVersionError` for any other `schemaVersion` value.
+ */
+export function readResult(filePath) {
+    const parsed = JSON.parse(readFileSync(filePath, 'utf8'));
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new UnknownSchemaVersionError(`Unknown schemaVersion: ${String(parsed)}. Supported: v1 (no field), v2.`);
+    }
+    const schemaVersion = parsed.schemaVersion;
+    if (schemaVersion === 'v2') {
+        return parsed;
+    }
+    if (schemaVersion === undefined) {
+        return parsed;
+    }
+    throw new UnknownSchemaVersionError(`Unknown schemaVersion: ${String(schemaVersion)}. Supported: v1 (no field), v2.`);
+}
+/**
+ * Serialize a v1 or v2 decomposition result to disk as pretty-printed JSON.
+ * The `schemaVersion` field (or its absence) is preserved as-is.
+ */
+export function writeResult(filePath, result) {
+    writeFileSync(filePath, JSON.stringify(result, null, 2), 'utf8');
+}

package/dist/services/slice/slice-archive-service.d.ts

@@ -0,0 +1,20 @@
+export declare const ARCHIVE_RETENTION_MS: number;
+export interface ArchiveResult {
+    readonly archivedCompleted: number;
+    readonly archivedInFlight: number;
+    readonly gcDeleted: number;
+}
+/** Build the canonical archive dir for a given session + slice id. */
+export declare function archiveDir(projectRoot: string, sessionId: string, sliceId: string): string;
+/** Build the in-flight subdir (records not yet disposed). */
+export declare function inFlightArchiveDir(projectRoot: string, sessionId: string, sliceId: string): string;
+/**
+ * Archive the current `.peaks/_sub_agents/<sid>/` tree under
+ * `<archiveDir>` (per the sliceId), separating completed vs in-flight.
+ * Then run the 30-day GC over the archive dir.
+ */
+export declare function archiveSubAgentRecords(projectRoot: string, options: {
+    sessionId: string;
+    sliceId: string;
+    now?: () => Date;
+}): ArchiveResult;