peaks-loop 4.0.0-beta.12 → 4.0.0-beta.15

package/dist/services/context/shared-channel.js

@@ -1,308 +0,0 @@
-/**
- * G8 — cross sub-agent shared channel (RL-23..RL-26, AC-47..AC-49).
- *
- * Dispatcher-mediated indirect signal: sub-agent A writes a shared entry,
- * the dispatcher stores it in a per-batch JSON file, sub-agent B (still
- * in flight) reads it. A and B never directly talk. This is the
- * pseudo-swarm property 3 upgrade; it is NOT peer-to-peer messaging.
- *
- * Path convention (G8.3):
- *   `.peaks/_sub_agents/<sid>/shared/<rid>-<batchId>.json`
- *
- * The file is atomic-write (tmp + rename). Last-write-wins by key. Value
- * size limit: ≤ 1KB soft warn, ≥ 64KB hard reject. File size cap: 1MB
- * with LRU eviction.
- *
- * See: `.peaks/memory/sub-agent-shared-channel-cross-completion.md` for
- * the full G8 rule.
- */
-import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
-import { assertSafeSharedChannelPath, sharedChannelPath } from './dispatch-context-guard.js';
-import { withFileLockSync } from '../filesystem/file-lock.js';
-export const SHARED_CHANNEL_MAX_VALUE_BYTES = 64 * 1024; // 64KB hard reject
-export const SHARED_CHANNEL_SOFT_VALUE_WARN = 1024; // 1KB soft warning
-export const SHARED_CHANNEL_MAX_FILE_BYTES = 1024 * 1024; // 1MB LRU cap
-export const SHARED_CHANNEL_TTL_DAYS = 30; // 30-day TTL on orphan channels
-/**
- * Write a shared entry to the per-batch channel file. Atomic-write
- * (tmp + rename). Returns the new entry + channel size + last-write-wins
- * flag (true if the key already existed; the new value overwrites).
- *
- * RL-25 size limit: `value ≥ 64KB` is hard-rejected with `VALUE_TOO_LARGE`.
- * `value > 1KB and < 64KB` is a soft warning (returned in the result).
- */
-export function writeSharedEntry(opts) {
-    if (typeof opts.key !== 'string' || opts.key.length === 0) {
-        return { ok: false, code: 'INVALID_BATCH_ID', message: 'key must be non-empty' };
-    }
-    if (typeof opts.from !== 'string' || opts.from.length === 0) {
-        return { ok: false, code: 'INVALID_BATCH_ID', message: 'from must be non-empty' };
-    }
-    if (opts.value === null || typeof opts.value !== 'object' || Array.isArray(opts.value)) {
-        return {
-            ok: false,
-            code: 'INVALID_BATCH_ID',
-            message: 'value must be a JSON object (not array, not primitive)'
-        };
-    }
-    const valueSize = Buffer.byteLength(JSON.stringify(opts.value), 'utf8');
-    if (valueSize >= SHARED_CHANNEL_MAX_VALUE_BYTES) {
-        return {
-            ok: false,
-            code: 'VALUE_TOO_LARGE',
-            message: `value size ${valueSize} bytes exceeds limit ${SHARED_CHANNEL_MAX_VALUE_BYTES} bytes (RL-25)`
-        };
-    }
-    const softWarning = valueSize > SHARED_CHANNEL_SOFT_VALUE_WARN;
-    const channelFile = sharedChannelPath(opts.projectRoot, opts.sid, opts.rid, opts.batchId);
-    assertSafeSharedChannelPath(channelFile, opts.projectRoot);
-    // Slice 2026-06-23-audit-3rd #2: the read-modify-write sequence below
-    // is wrapped in withFileLockSync to prevent lost updates from two
-    // concurrent `peaks sub-agent share` calls landing on the same batch.
-    // Without the lock, the second writer's read sees a stale channel,
-    // and its renameSync silently overwrites the first writer's entry.
-    return withFileLockSync(channelFile, () => {
-        let channel;
-        try {
-            channel = readChannelOrEmpty(channelFile, opts.batchId);
-        }
-        catch (err) {
-            return {
-                ok: false,
-                code: 'WRITE_ERROR',
-                message: `failed to read existing channel: ${err.message}`
-            };
-        }
-        const lastWriteWins = Object.prototype.hasOwnProperty.call(channel.entries, opts.key);
-        // LRU eviction: if writing would push the file over the 1MB cap,
-        // evict oldest entries until the new write fits.
-        const entry = {
-            version: 1,
-            at: new Date().toISOString(),
-            from: opts.from,
-            key: opts.key,
-            value: Object.freeze({ ...opts.value }),
-            valueSize
-        };
-        const projectedChannel = {
-            ...channel,
-            updatedAt: entry.at,
-            entries: { ...channel.entries, [opts.key]: entry }
-        };
-        const projectedSize = JSON.stringify(projectedChannel).length;
-        let lruEvicted = 0;
-        if (projectedSize > SHARED_CHANNEL_MAX_FILE_BYTES) {
-            const sortedKeys = Object.keys(projectedChannel.entries).sort((a, b) => {
-                const ea = projectedChannel.entries[a];
-                const eb = projectedChannel.entries[b];
-                if (!ea || !eb)
-                    return 0;
-                return ea.at.localeCompare(eb.at);
-            });
-            let working = projectedChannel;
-            while (JSON.stringify(working).length > SHARED_CHANNEL_MAX_FILE_BYTES &&
-                sortedKeys.length > 0) {
-                const oldestKey = sortedKeys.shift();
-                if (oldestKey === opts.key) {
-                    // Don't evict the entry we just wrote.
-                    break;
-                }
-                const nextEntries = {};
-                for (const [k, v] of Object.entries(working.entries)) {
-                    if (k !== oldestKey) {
-                        nextEntries[k] = v;
-                    }
-                }
-                working = { ...working, entries: nextEntries };
-                lruEvicted += 1;
-            }
-            try {
-                writeAtomic(channelFile, working);
-            }
-            catch (err) {
-                return {
-                    ok: false,
-                    code: 'WRITE_ERROR',
-                    message: `failed to write channel after LRU eviction: ${err.message}`
-                };
-            }
-            return {
-                ok: true,
-                entry,
-                channelSize: JSON.stringify(working).length,
-                lastWriteWins,
-                softWarning
-            };
-        }
-        try {
-            writeAtomic(channelFile, projectedChannel);
-        }
-        catch (err) {
-            return {
-                ok: false,
-                code: 'WRITE_ERROR',
-                message: `failed to write channel: ${err.message}`
-            };
-        }
-        // lruEvicted is 0 here; expose the count through the size of the
-        // returned channel for caller diagnostics.
-        void lruEvicted;
-        return {
-            ok: true,
-            entry,
-            channelSize: projectedSize,
-            lastWriteWins,
-            softWarning
-        };
-    });
-}
-/**
- * Read the shared channel for a batch. Returns the channel with all
- * matching entries. Filters: `--since` (ISO8601) and `--key` (glob
- * pattern; simple `*` wildcard, no regex).
- *
- * If the channel file does not exist, returns an empty channel
- * (this is the dispatcher's "fresh batch" view).
- */
-export function readSharedChannel(opts) {
-    const channelFile = sharedChannelPath(opts.projectRoot, opts.sid, opts.rid, opts.batchId);
-    assertSafeSharedChannelPath(channelFile, opts.projectRoot);
-    const channel = readChannelOrEmpty(channelFile, opts.batchId);
-    const since = opts.since;
-    const pattern = opts.keyPattern;
-    if (!since && !pattern) {
-        return channel;
-    }
-    const filteredEntries = {};
-    const matcher = pattern ? compileKeyPattern(pattern) : null;
-    for (const [k, v] of Object.entries(channel.entries)) {
-        if (since && v.at < since)
-            continue;
-        if (matcher && !matcher(k))
-            continue;
-        filteredEntries[k] = v;
-    }
-    return { ...channel, entries: filteredEntries };
-}
-/**
- * Garbage-collect a single channel. Returns true if the file was
- * deleted, false if it did not exist.
- */
-export function gcChannel(opts) {
-    const channelFile = sharedChannelPath(opts.projectRoot, opts.sid, opts.rid, opts.batchId);
-    if (!existsSync(channelFile)) {
-        return false;
-    }
-    // Best-effort delete; R-2 guard not strictly needed (we built the path)
-    // but kept for safety.
-    assertSafeSharedChannelPath(channelFile, opts.projectRoot);
-    try {
-        unlinkSync(channelFile);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Check if a channel file is older than `SHARED_CHANNEL_TTL_DAYS` days
- * and should be GC'd as an orphan. Returns true if file is missing
- * (already GC'd) or older than TTL.
- */
-export function isOrphanChannel(opts) {
-    const channelFile = sharedChannelPath(opts.projectRoot, opts.sid, opts.rid, opts.batchId);
-    if (!existsSync(channelFile)) {
-        return true;
-    }
-    const s = statSync(channelFile);
-    const now = opts.now ?? new Date();
-    const ageMs = now.getTime() - s.mtimeMs;
-    const ttlMs = SHARED_CHANNEL_TTL_DAYS * 24 * 60 * 60 * 1000;
-    return ageMs > ttlMs;
-}
-// ─── internals ───────────────────────────────────────────────────────
-function readChannelOrEmpty(channelFile, batchId) {
-    if (!existsSync(channelFile)) {
-        const now = new Date().toISOString();
-        return { batchId, createdAt: now, updatedAt: now, entries: {} };
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(readFileSync(channelFile, 'utf8'));
-    }
-    catch {
-        const now = new Date().toISOString();
-        return { batchId, createdAt: now, updatedAt: now, entries: {} };
-    }
-    if (!isObject(parsed)) {
-        const now = new Date().toISOString();
-        return { batchId, createdAt: now, updatedAt: now, entries: {} };
-    }
-    const obj = parsed;
-    const batchIdField = typeof obj.batchId === 'string' ? obj.batchId : batchId;
-    const createdAt = typeof obj.createdAt === 'string' ? obj.createdAt : new Date().toISOString();
-    const updatedAt = typeof obj.updatedAt === 'string' ? obj.updatedAt : createdAt;
-    const entriesField = isObject(obj.entries) ? obj.entries : {};
-    const entries = {};
-    for (const [k, v] of Object.entries(entriesField)) {
-        if (isValidEntry(v)) {
-            entries[k] = v;
-        }
-    }
-    return { batchId: batchIdField, createdAt, updatedAt, entries };
-}
-function isValidEntry(v) {
-    if (!isObject(v))
-        return false;
-    // Slice 2026-06-23-audit-4th #E2: pre-versioning records (no
-    // `version` field) are still accepted on read for backward compat.
-    // The writer stamps `version: 1` going forward; readers default
-    // missing/legacy entries to version 1 in memory.
-    if (!('version' in v) || v.version === 1) {
-        return (typeof v.at === 'string' &&
-            typeof v.from === 'string' &&
-            typeof v.key === 'string' &&
-            isObject(v.value) &&
-            typeof v.valueSize === 'number');
-    }
-    // Future versions: read-side handler can branch on `v.version` once
-    // v2 lands. For now, anything other than 1 is rejected.
-    return false;
-}
-function isObject(v) {
-    return typeof v === 'object' && v !== null && !Array.isArray(v);
-}
-function writeAtomic(path, channel) {
-    const dir = dirname(path);
-    // Slice 2026-06-23-audit-3rd #11: skip mkdirSync when the dir already
-    // exists. The `recursive: true` mkdir is a syscall (~50µs on macOS,
-    // ~10ms on cold Windows cache); the `existsSync` short-circuit saves
-    // it on the hot path (every `peaks sub-agent share` + every
-    // `peaks sub-agent heartbeat`).
-    if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true });
-    }
-    const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
-    writeFileSync(tmp, JSON.stringify(channel, null, 2) + '\n', 'utf8');
-    renameSync(tmp, path);
-}
-/**
- * Compile a simple key pattern with `*` wildcards to a matcher. Only
- * `*` is special; everything else is a literal. `*` matches zero or
- * more characters. Examples:
- *   "rd.*"       matches "rd.completed", "rd.found-blocker"
- *   "*.completed" matches "rd.completed", "qa.completed"
- *   "*"           matches everything
- */
-export function compileKeyPattern(pattern) {
-    if (pattern === '*') {
-        return () => true;
-    }
-    const escaped = pattern
-        .split('*')
-        .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
-        .join('.*');
-    const re = new RegExp(`^${escaped}$`);
-    return (key) => re.test(key);
-}

package/dist/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 {};