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

package/dist/src/services/context/threshold.js

@@ -1,76 +0,0 @@
-/**
- * G9.3 — forced compression gate threshold constants + tier evaluation.
- *
- * 256K default context capacity is a conservative proxy. The LLM's real
- * capacity is its private business (R-1 / R-8 / R-10 / R-13 boundary
- * inherited from slice #009); we use prompt size as the gate signal.
- *
- * See: `.peaks/memory/sub-agent-headroom-forced-compression-gate.md`
- * for the full G9 rule (RL-27..RL-32, AC-50..AC-65).
- */
-export const CONTEXT_CAPACITY_DEFAULT_BYTES = 256 * 1024; // 256K
-export const THRESHOLD_SOFT_WARN_RATIO = 0.5; // 50%
-export const THRESHOLD_NEAR_LIMIT_RATIO = 0.75; // 75% — user red line
-export const THRESHOLD_HARD_REJECT_RATIO = 0.80; // 80%
-export const THRESHOLD_EMERGENCY_RATIO = 0.90; // 90%
-/**
- * Compute the threshold tier for a given prompt size. Pure function
- * (no IO, no side effects). The `capacityBytes` parameter lets callers
- * override the default 256K proxy (e.g. for testing or for a future
- * per-IDE capacity override).
- */
-export function evaluateThresholdTier(promptSize, capacityBytes = CONTEXT_CAPACITY_DEFAULT_BYTES) {
-    if (!Number.isFinite(promptSize) || promptSize < 0) {
-        throw new Error(`evaluateThresholdTier: promptSize must be ≥ 0 (got ${promptSize})`);
-    }
-    if (!Number.isFinite(capacityBytes) || capacityBytes <= 0) {
-        throw new Error(`evaluateThresholdTier: capacityBytes must be > 0 (got ${capacityBytes})`);
-    }
-    const ratio = promptSize / capacityBytes;
-    const warnings = [];
-    let tier;
-    if (ratio >= THRESHOLD_EMERGENCY_RATIO) {
-        tier = 'emergency';
-        warnings.push('PROMPT_EMERGENCY');
-    }
-    else if (ratio >= THRESHOLD_HARD_REJECT_RATIO) {
-        tier = 'hard-reject';
-        warnings.push('PROMPT_TOO_LARGE');
-    }
-    else if (ratio >= THRESHOLD_NEAR_LIMIT_RATIO) {
-        tier = 'near-limit';
-        warnings.push('CONTEXT_NEAR_LIMIT');
-    }
-    else if (ratio >= THRESHOLD_SOFT_WARN_RATIO) {
-        tier = 'soft-warn';
-        warnings.push('CONTEXT_SOFT_WARN');
-    }
-    else {
-        tier = 'ok';
-    }
-    return {
-        tier,
-        ratio,
-        bytesUsed: promptSize,
-        capacityBytes,
-        warnings
-    };
-}
-/**
- * Convert a threshold tier to a machine-readable code suitable for the
- * CLI envelope's `code` field. Used by both the CLI and the hook layer.
- */
-export function tierToCode(tier) {
-    switch (tier) {
-        case 'ok':
-            return 'OK';
-        case 'soft-warn':
-            return 'CONTEXT_SOFT_WARN';
-        case 'near-limit':
-            return 'CONTEXT_NEAR_LIMIT';
-        case 'hard-reject':
-            return 'PROMPT_TOO_LARGE';
-        case 'emergency':
-            return 'PROMPT_EMERGENCY';
-    }
-}

package/dist/src/services/context/tokenizer.d.ts

@@ -1,12 +0,0 @@
-/**
- * Per spec §4.1 Step 3 — Tokenizer (non-mutating).
- *
- * Hard constraint H3: structured metadata > bare strings. Each collector
- * artifact and each fetched doc gets a tokenized metadata record so
- * peaks-rd/qa can do relative-anomaly detection later.
- *
- * Immutability H (common/coding-style): the output is frozen so callers
- * cannot mutate it. Use spread to derive new outputs in future slices.
- */
-import type { CollectorOutput, DocRetrieverOutput, TokenizerOutput } from './types.js';
-export declare function tokenize(collector: CollectorOutput, docRetriever: DocRetrieverOutput, now?: Date): TokenizerOutput;

package/dist/src/services/context/tokenizer.js

@@ -1,43 +0,0 @@
-function freshDecayScore(fetchedAt, now) {
-    const ageMs = now.getTime() - new Date(fetchedAt).getTime();
-    const ageDays = ageMs / (1000 * 60 * 60 * 24);
-    // Linear decay: 1.0 at day 0, 0.5 at day 30, 0.0 at day 60+
-    if (ageDays >= 60)
-        return 0;
-    return Math.max(0, 1 - ageDays / 60);
-}
-export function tokenize(collector, docRetriever, now = new Date()) {
-    const metadata = [];
-    for (const doc of docRetriever.fetchedDocs) {
-        metadata.push({
-            id: `doc:${doc.dep}@${doc.version}`,
-            kind: 'doc',
-            version: doc.version,
-            blastRadius: doc.sections.map((s) => s.title),
-            conflictScore: 0, // v1: no cross-source conflict detection yet
-            timeDecayScore: freshDecayScore(doc.fetchedAt, now),
-            tags: ['fetched', doc.source, doc.stale ? 'stale' : 'fresh'],
-        });
-    }
-    for (const mem of collector.memoryEntries) {
-        metadata.push({
-            id: `memory:${mem.path}`,
-            kind: 'memory',
-            blastRadius: [mem.title],
-            conflictScore: 0,
-            timeDecayScore: mem.relevanceScore,
-            tags: ['memory'],
-        });
-    }
-    for (const file of collector.files) {
-        metadata.push({
-            id: `code:${file.path}`,
-            kind: 'code',
-            blastRadius: [file.path],
-            conflictScore: 0,
-            timeDecayScore: 1,
-            tags: [file.kind],
-        });
-    }
-    return Object.freeze({ metadata: Object.freeze(metadata) });
-}

package/dist/src/services/context/types.d.ts

@@ -1,93 +0,0 @@
-/**
- * Per spec §4.1 — the single source of truth for context.json shape.
- * The Zod schema in context-schema.ts must mirror this interface exactly;
- * the schema is the runtime validator, the interface is the compile-time contract.
- *
- * Hard constraint H8: Audit trail must be hashable. `sha256` is the field
- * that lets peaks-state-lock chain signatures between stages.
- */
-export type ContextVersion = '1.0';
-export type Audience = 'peaks-rd' | 'peaks-qa' | 'peaks-mut' | 'all';
-export type DepsMode = 'locked' | 'latest';
-export type FileKind = 'source' | 'test' | 'config' | 'doc';
-export interface CollectedFile {
-    readonly path: string;
-    readonly kind: FileKind;
-    readonly lines: number;
-    readonly hash: string;
-}
-export interface GitStatus {
-    readonly branch: string;
-    readonly lastCommit: string;
-    readonly dirty: boolean;
-}
-export interface MemoryEntry {
-    readonly path: string;
-    readonly title: string;
-    readonly relevanceScore: number;
-    readonly excerptHash: string;
-}
-export interface DepInfo {
-    readonly version: string;
-    readonly source: 'package.json' | 'pnpm-lock.yaml' | 'yarn.lock';
-    readonly resolved: string;
-}
-export interface DocSection {
-    readonly title: string;
-    readonly tokenEstimate: number;
-    readonly excerpt: string;
-}
-export interface FetchedDoc {
-    readonly dep: string;
-    readonly version: string;
-    readonly source: 'local-cache' | 'remote-fetch';
-    readonly url?: string;
-    readonly fetchedAt: string;
-    readonly contentHash: string;
-    readonly sections: ReadonlyArray<DocSection>;
-    readonly stale: boolean;
-}
-export interface SkippedDoc {
-    readonly dep: string;
-    readonly reason: 'unconfigured' | 'network_error' | 'version_unknown';
-}
-export type MetaKind = 'doc' | 'code' | 'memory' | 'git';
-export interface TokenizedItem {
-    readonly id: string;
-    readonly kind: MetaKind;
-    readonly version?: string;
-    readonly blastRadius: ReadonlyArray<string>;
-    readonly conflictScore: number;
-    readonly timeDecayScore: number;
-    readonly tags: ReadonlyArray<string>;
-}
-export interface CollectorOutput {
-    readonly files: ReadonlyArray<CollectedFile>;
-    readonly gitStatus: GitStatus;
-    readonly memoryEntries: ReadonlyArray<MemoryEntry>;
-    readonly deps: Readonly<Record<string, DepInfo>>;
-}
-export interface DocRetrieverOutput {
-    readonly fetchedDocs: ReadonlyArray<FetchedDoc>;
-    readonly skipped: ReadonlyArray<SkippedDoc>;
-}
-export interface TokenizerOutput {
-    readonly metadata: ReadonlyArray<TokenizedItem>;
-}
-export interface RendererOutput {
-    readonly audience: Audience;
-    readonly renderedAt: string;
-    readonly sizeBytes: number;
-    readonly truncated: boolean;
-    readonly truncatedReason?: 'doc_budget_exceeded' | 'section_count_exceeded';
-}
-export interface ContextJson {
-    readonly version: ContextVersion;
-    readonly goal: string;
-    readonly generatedAt: string;
-    readonly sha256: string;
-    readonly collector: CollectorOutput;
-    readonly docRetriever: DocRetrieverOutput;
-    readonly tokenizer: TokenizerOutput;
-    readonly renderer: RendererOutput;
-}

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

@@ -1,9 +0,0 @@
-/**
- * Per spec §4.1 — the single source of truth for context.json shape.
- * The Zod schema in context-schema.ts must mirror this interface exactly;
- * the schema is the runtime validator, the interface is the compile-time contract.
- *
- * Hard constraint H8: Audit trail must be hashable. `sha256` is the field
- * that lets peaks-state-lock chain signatures between stages.
- */
-export {};

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

@@ -1,239 +0,0 @@
-import type Database from "better-sqlite3";
-import { z } from "zod";
-import { type CrystallizationEvent, type CrystallizationEventInput, type CrystallizationEventStatus, type EvidenceBrief } from "./crystallization-types.js";
-import { listCrystallizationEvents } from "./crystallization-store.js";
-import { type LoopReleaseInput } from "../loop/loop-release-types.js";
-/**
- * CrystallizationService — spec §5 (post-run crystallization)
- * + §4.5 + §4.7 + §10 RL-2 / RL-3 / RL-7.
- *
- * Hard rules enforced at THIS layer (defense in depth; the Zod
- * schemas above and the brief refine guard add the second wall):
- *
- *   - AC-4 / RL-2: a crystallization_event is written only when the
- *     candidate task has `task_status === 'completed'` AND
- *     `gates_passed === true` AND `evidence_collected === true`.
- *     Any pre-run attempt (status !== 'completed') is rejected
- *     with `CRYSTALLIZATION_PRE_RUN`. This is the pre-run block
- *     enforced by AC-4, AC-5, AC-6, AC-15, AC-16, AC-17 of the M5
- *     slice.
- *   - AC-6 / RL-3: writing a (loop_release, main_bee_release,
- *     loop_bee_relation) pair happens in a SINGLE TRANSACTION. The
- *     brief persist on crystallization_event also lives inside
- *     the same transaction (the brief is the durable evidence;
- *     dropping either side would break consistency).
- *   - AC-7 / RL-1: this layer never asks the user to hand-author
- *     JSON / manifest / CLI verb; all inputs are typed payloads
- *     the LLM submits on the user's behalf.
- *   - AC-15 / RL-7: the brief is mandatory; the
- *     `EvidenceBriefSchema.refine` guard rejects partial briefs
- *     at the parse boundary.
- *   - AC-16 / RL-7: the brief has all 4 sections
- *     (what_happened / why_it_matters / what_learned /
- *     what_action). The service throws `BriefSectionError` if the
- *     payload fails the guard.
- *
- * Sub-domain error codes:
- *
- *   - CRYSTALLIZATION_PRE_RUN: task_status / gates_passed /
- *     evidence_collected precondition failed.
- *   - CRYSTALLIZATION_INVALID_TASK_STATE: a task input field is
- *     malformed (e.g. unknown task_status).
- *   - MISSING_BRIEF_SECTION: a brief is missing at least one of
- *     its 4 sections (raised from the evidence-brief-builder
- *     refine; surfaced as-is by the service).
- *   - CRYSTALLIZATION_TX_FAILED: a transaction-side effect failed
- *     (FK constraint, duplicate key, …). The service re-raises
- *     richer domain errors first; this is the catch-all for
- *     unexpected SQL errors.
- */
-export declare const CRYSTALLIZATION_TASK_STATUSES: readonly ["completed", "in_progress", "scratch", "blocked", "failed"];
-export type CrystallizationTaskStatus = (typeof CRYSTALLIZATION_TASK_STATUSES)[number];
-/**
- * The pre-run task state the service requires. Crystallization is
- * GATED on these three flags. The validator rejects any input that
- * does not match. Adding a new flag means a schema-version bump; for
- * now the three are required.
- */
-export declare const CrystallizationTaskStateSchema: z.ZodObject<{
-    task_id: z.ZodString;
-    task_status: z.ZodLiteral<"completed">;
-    gates_passed: z.ZodLiteral<true>;
-    evidence_collected: z.ZodLiteral<true>;
-}, "strip", z.ZodTypeAny, {
-    task_id: string;
-    task_status: "completed";
-    gates_passed: true;
-    evidence_collected: true;
-}, {
-    task_id: string;
-    task_status: "completed";
-    gates_passed: true;
-    evidence_collected: true;
-}>;
-export type CrystallizationTaskState = z.infer<typeof CrystallizationTaskStateSchema>;
-export type CrystallizationIntegrityErrorCode = "CRYSTALLIZATION_PRE_RUN" | "CRYSTALLIZATION_INVALID_TASK_STATE" | "CRYSTALLIZATION_TX_FAILED" | "MISSING_BRIEF_SECTION";
-export declare class CrystallizationIntegrityError extends Error {
-    readonly code: CrystallizationIntegrityErrorCode | "MISSING_BRIEF_SECTION";
-    readonly findings: ReadonlyArray<{
-        path: string;
-        message: string;
-    }>;
-    constructor(code: CrystallizationIntegrityErrorCode, message: string, findings?: ReadonlyArray<{
-        path: string;
-        message: string;
-    }>);
-}
-export interface CrystallizePayload {
-    /** The candidate task state. Must satisfy the pre-run gate. */
-    task: CrystallizationTaskState;
-    /** The loop_release to create (new). Must include main bee via relation. */
-    loop_input: LoopReleaseInput;
-    /**
-     * The main bee_release to create. Note: bee_release requires a
-     * manifest row to keep the existing 4.x schema consistent;
-     * `bee_input` here carries ONLY the manifest-level fields the
-     * service uses. A future slice will swap in the full
-     * retainRelease() flow.
-     */
-    bee_input: BeeCrystallizeInput;
-    /**
-     * Optional NL reason the LLM authored; surfaced on the
-     * loop_bee_relation row (spec §4.6 `reason`).
-     */
-    bee_relation_reason: string;
-    /**
-     * The 4-section evidence brief (spec §4.7).
-     */
-    evidence_brief: EvidenceBrief;
-    /** Optional structured bullets (RL-7: counts may support the brief, not replace it). */
-    evidence_bullets?: string[];
-    /** Source trace pointers for the brief (spec §4.5). */
-    source_trace_pointers?: string[];
-    /** Optional evaluator summary (independent scorers — spec §4.5). */
-    evaluator_summary?: string;
-    /** Optional user decision summary (spec §4.5). */
-    user_decision_summary?: string;
-    /** Trigger classification (spec §5.4). */
-    trigger: CrystallizationEventInput["trigger"];
-}
-/**
- * Minimum bee_release payload the service needs to create a main bee
- * alongside a loop. The full bee_release schema (see
- * `src/services/skillhub/release-retain.ts`) carries manifest rows,
- * segment refs, file rows, etc.; M5 only writes the bee_release header
- * + a single bee_manifest row sufficient to keep the 4.x FK
- * constraints green. Full bee retaining lands in a future slice.
- *
- * Schema definition is hoisted above the interface so the typed
- * interface can reference the inferred Zod type without forward-
- * reference gymnastics.
- */
-declare const BeeNameSchema: z.ZodString;
-export interface BeeCrystallizeInput {
-    bee_name: z.infer<typeof BeeNameSchema>;
-    version: string;
-    description: string;
-    user_intent_raw?: string;
-    parent_version?: string;
-    changelog?: string;
-}
-/**
- * The crystallization result. The brief is returned AS PERSISTED
- * (re-parsed through the schema) so callers receive the canonical
- * shape, not the loose payload.
- */
-export interface CrystallizationResult {
-    loop_release_id: string;
-    bee_release_id: number;
-    loop_bee_relation_id: number;
-    crystallization_event_id: string;
-    loop_release_lifecycle_status: CrystallizationEventStatus;
-}
-/**
- * Service interface for the post-run crystallization flow.
- */
-export declare class CrystallizationService {
-    private readonly db;
-    constructor(db: Database.Database);
-    /**
-     * Read a CrystallizationEvent by id.
-     */
-    read(id: string): CrystallizationEvent | undefined;
-    /**
-     * List events. Filter by lifecycle_status and/or the FK pointer
-     * columns. When no filters are supplied, lists ALL events
-     * (newest-first).
-     */
-    list(opts?: Parameters<typeof listCrystallizationEvents>[1]): {
-        schema_version: "peaks.crystallization/1";
-        id: string;
-        lifecycle_status: "candidate" | "stable" | "retired";
-        trigger: "user_explicit" | "llm_suggested" | "success_default_prompt" | "similar_task_recurrence";
-        evidence_brief: {
-            what_happened: string;
-            why_it_matters: string;
-            what_learned: string;
-            what_action: string;
-        };
-        evidence_bullets: string[];
-        source_trace_pointers: string[];
-        evaluator_summary: string;
-        user_decision_summary: string;
-        created_at: string;
-        created_loop_release_id?: string | undefined;
-        updated_loop_release_id?: string | undefined;
-        created_bee_release_id?: number | undefined;
-        updated_bee_release_id?: number | undefined;
-    }[];
-    /**
-     * Update a crystallization event's lifecycle_status. Always allowed
-     * (no schema-version gate). Returns the updated row or undefined if
-     * the id is absent.
-     *
-     * A `stable` transition is the natural post-crystallization state;
-     * the service does NOT enforce user-confirmation here (per spec
-     * §5.6 promotion happens on a separate `peaks loop promote` path).
-     * `retired` is the dispose path (`peaks asset dispose`).
-     */
-    updateStatus(id: string, next: CrystallizationEventStatus): CrystallizationEvent | undefined;
-    /**
-     * Pre-run gate: throws if any of `task_status`, `gates_passed`,
-     * `evidence_collected` is not as required. Called from
-     * `crystallize` BEFORE the transaction begins.
-     *
-     * Reachable as a public method so the CLI / tests can probe the
-     * gate in isolation.
-     */
-    assertReady(task: CrystallizationTaskState): CrystallizationTaskState;
-    /**
-     * Run the post-run crystallization flow.
-     *
-     * Steps (all in ONE better-sqlite3 transaction, atomic):
-     *
-     *   1. Pre-run gate (task must be completed / gates_passed /
-     *      evidence_collected).
-     *   2. Re-validate the 4-section brief (EvidenceBriefSchema.parse,
-     *      EvidenceBriefSchema.refine).
-     *   3. Insert loop_release.
-     *   4. Insert bee_release header (+ a single bee_manifest row to
-     *      keep the 4.x FK contract).
-     *   5. Insert loop_bee_relation row with role='main'.
-     *   6. Insert crystallization_event with the brief persisted.
-     *
-     * Returns the four ids + the new loop's lifecycle_status. On any
-     * failure the transaction is rolled back and the partial rows
-     * disappear.
-     *
-     * Throws:
-     *   - CrystallizationIntegrityError(CRYSTALLIZATION_PRE_RUN) on
-     *     the pre-run gate.
-     *   - BriefSectionError or ZodError if the brief is malformed;
-     *     surfaced as
-     *     CrystallizationIntegrityError(MISSING_BRIEF_SECTION).
-     *   - CrystallizationIntegrityError(CRYSTALLIZATION_TX_FAILED)
-     *     on any SQL transaction failure.
-     */
-    crystallize(payload: CrystallizePayload): CrystallizationResult;
-}
-export {};