@lumenflow/core 3.1.2 → 3.2.0

package/dist/wu-state-store.d.ts

@@ -1,275 +0,0 @@
-import { type WUEvent } from './wu-state-schema.js';
-/**
- * WU events file name constant
- */
-export declare const WU_EVENTS_FILE_NAME = "wu-events.jsonl";
-/**
- * WU state entry in the in-memory store
- */
-export interface WUStateEntry {
-    status: string;
-    lane: string;
-    title: string;
-    completedAt?: string;
-    lastCheckpoint?: string;
-    lastCheckpointNote?: string;
-}
-/**
- * Lock file data structure
- */
-export interface LockData {
-    pid: number;
-    timestamp: number;
-    hostname: string;
-}
-/**
- * Checkpoint options
- */
-export interface CheckpointOptions {
-    sessionId?: string;
-    progress?: string;
-    nextSteps?: string;
-}
-/**
- * Repair result
- */
-export interface RepairResult {
-    success: boolean;
-    linesKept: number;
-    linesRemoved: number;
-    backupPath: string | null;
-    warnings: string[];
-}
-/**
- * WU State Store class
- *
- * Manages WU lifecycle state via event sourcing pattern.
- * Events are appended to JSONL file, state is rebuilt by replaying events.
- */
-export declare class WUStateStore {
-    private readonly baseDir;
-    private readonly eventsFilePath;
-    private wuState;
-    private byStatus;
-    private byLane;
-    private byParent;
-    constructor(baseDir: string);
-    /**
-     * WU-1674: On first run, archive spawn-era state files and rebuild wu-events.jsonl
-     * using delegation-era semantics. This migration only runs for canonical state dirs
-     * (<repo>/.lumenflow/state) and is guarded by a one-time marker file.
-     */
-    private _runDelegationCutoverIfNeeded;
-    /**
-     * Loads and replays events from JSONL file into current state.
-     *
-     * Handles:
-     * - Missing file: returns empty state
-     * - Empty file: returns empty state
-     * - Empty lines: skipped gracefully
-     * - Malformed JSON: throws error with line info
-     * - Invalid events: throws validation error
-     *
-     * @throws Error If file contains malformed JSON or invalid events
-     *
-     * @example
-     * const store = new WUStateStore('/path/to/project');
-     * await store.load();
-     * const inProgress = store.getByStatus('in_progress');
-     */
-    load(): Promise<void>;
-    /**
-     * Transition WU to a new status if it exists.
-     */
-    private _transitionToStatus;
-    /**
-     * Applies an event to the in-memory state.
-     */
-    private _applyEvent;
-    /**
-     * Sets WU state and updates indexes.
-     */
-    private _setState;
-    /**
-     * Appends an event to the events file.
-     *
-     * Uses append mode to avoid full file rewrite.
-     * Creates file and parent directories if they don't exist.
-     * Validates event before appending.
-     *
-     * @throws Error If event fails validation
-     */
-    private _appendEvent;
-    /**
-     * Claims a WU (transitions to in_progress).
-     *
-     * @throws Error If WU is already in_progress
-     *
-     * @example
-     * await store.claim('WU-1570', 'Operations: Tooling', 'Test WU');
-     */
-    claim(wuId: string, lane: string, title: string): Promise<void>;
-    /**
-     * Completes a WU (transitions to done).
-     *
-     * @throws Error If WU is not in_progress
-     *
-     * @example
-     * await store.complete('WU-1570');
-     */
-    complete(wuId: string): Promise<void>;
-    /**
-     * Get current in-memory state for a WU.
-     */
-    getWUState(wuId: string): WUStateEntry | undefined;
-    /**
-     * Create a complete event without writing to disk.
-     *
-     * Used by transactional flows where event log writes are staged and committed atomically.
-     *
-     * @throws Error If WU is not in_progress or event fails validation
-     */
-    createCompleteEvent(wuId: string, timestamp?: string): WUEvent;
-    /**
-     * Apply a validated event to in-memory state without writing to disk.
-     *
-     * @throws Error If event fails validation
-     */
-    applyEvent(event: WUEvent): void;
-    /**
-     * Blocks a WU (transitions to blocked).
-     *
-     * @throws Error If WU is not in_progress
-     *
-     * @example
-     * await store.block('WU-1570', 'Blocked by dependency');
-     */
-    block(wuId: string, reason: string): Promise<void>;
-    /**
-     * Unblocks a WU (transitions back to in_progress).
-     *
-     * @throws Error If WU is not blocked
-     *
-     * @example
-     * await store.unblock('WU-1570');
-     */
-    unblock(wuId: string): Promise<void>;
-    /**
-     * Records a checkpoint for a WU (WU-1748: cross-agent visibility).
-     *
-     * Checkpoints are recorded for visibility but don't change WU state.
-     * Used to track progress and detect abandoned WUs.
-     *
-     * @example
-     * await store.checkpoint('WU-1748', 'Completed worktree scanner', {
-     *   progress: 'Scanner implemented and tests passing',
-     *   nextSteps: 'Integrate into orchestrate:monitor'
-     * });
-     */
-    checkpoint(wuId: string, note: string, options?: CheckpointOptions): Promise<void>;
-    /**
-     * Gets WU IDs by status (O(1) lookup).
-     *
-     * @example
-     * const inProgress = store.getByStatus('in_progress');
-     * for (const wuId of inProgress) {
-     *   console.log(wuId);
-     * }
-     */
-    getByStatus(status: string): Set<string>;
-    /**
-     * Gets WU IDs by lane (O(1) lookup).
-     *
-     * @example
-     * const tooling = store.getByLane('Operations: Tooling');
-     * for (const wuId of tooling) {
-     *   console.log(wuId);
-     * }
-     */
-    getByLane(lane: string): Set<string>;
-    /**
-     * Gets child WU IDs delegated from a parent WU (O(1) lookup).
-     * WU-1947: Parent-child relationship tracking.
-     *
-     * @example
-     * const children = store.getChildWUs('WU-100');
-     * for (const childId of children) {
-     *   console.log(`Child WU: ${childId}`);
-     * }
-     */
-    getChildWUs(parentWuId: string): Set<string>;
-    /**
-     * Records a delegation relationship between parent and child WUs.
-     * WU-1947: Parent-child relationship tracking.
-     *
-     * @example
-     * await store.delegate('WU-200', 'WU-100', 'dlg-abc123');
-     */
-    delegate(childWuId: string, parentWuId: string, delegationId: string): Promise<void>;
-    /**
-     * Releases an in_progress WU back to ready state (WU-1080: orphan recovery).
-     *
-     * Use this when an agent is interrupted mid-WU and the WU needs to be
-     * made available for reclaiming by another agent.
-     *
-     * @throws Error If WU is not in_progress
-     *
-     * @example
-     * await store.release('WU-1080', 'Agent interrupted mid-WU');
-     */
-    release(wuId: string, reason: string): Promise<void>;
-    /**
-     * Create a release event without writing to disk.
-     *
-     * Used by transactional flows where event log writes are staged and committed atomically.
-     * WU-1080: Orphan recovery support.
-     *
-     * @throws Error If WU is not in_progress or event fails validation
-     */
-    createReleaseEvent(wuId: string, reason: string, timestamp?: string): WUEvent;
-}
-/**
- * Check if a lock is stale (expired or dead process)
- *
- * WU-2240: Prepared for proper-lockfile integration
- */
-export declare function isLockStale(lockData: LockData): boolean;
-/**
- * Acquire a file lock for the events file
- *
- * Uses a JSON lock file containing PID, timestamp, and hostname.
- * Implements stale lock detection via:
- * - PID check (on same host)
- * - 5-minute timeout (across hosts)
- *
- * WU-2240: Prepared for proper-lockfile integration
- *
- * @throws Error If lock cannot be acquired after retries
- */
-export declare function acquireLock(lockPath: string): Promise<void>;
-/**
- * Release a file lock
- *
- * WU-2240: Prepared for proper-lockfile integration
- */
-export declare function releaseLock(lockPath: string): void;
-/**
- * Repair a corrupted state file by removing invalid lines.
- *
- * WU-2240: Corruption recovery for wu-events.jsonl
- *
- * Features:
- * - Creates backup before repair
- * - Removes malformed JSON lines
- * - Removes lines that fail schema validation
- * - Returns detailed repair statistics
- *
- * @example
- * const stateFilePath = path.join(process.cwd(), '.lumenflow', 'state', 'wu-events.jsonl');
- * const result = await repairStateFile(stateFilePath);
- * if (result.success) {
- *   console.log(`Repaired: kept ${result.linesKept}, removed ${result.linesRemoved}`);
- * }
- */
-export declare function repairStateFile(filePath: string): Promise<RepairResult>;
-//# sourceMappingURL=wu-state-store.d.ts.map

package/dist/wu-state-store.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"wu-state-store.d.ts","sourceRoot":"","sources":["../src/wu-state-store.ts"],"names":[],"mappings":"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"}