@lumenflow/core 1.0.0

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

@@ -0,0 +1,213 @@
+/**
+ * WU State Schema (WU-1570)
+ *
+ * Zod schemas for WU state event validation.
+ * Defines event types for WU lifecycle: create, claim, block, unblock, complete.
+ *
+ * @see {@link tools/lib/__tests__/wu-state-store.test.mjs} - Tests
+ */
+import { z } from 'zod';
+/**
+ * WU event types
+ *
+ * - create: WU created (transitions to ready)
+ * - claim: WU claimed (transitions to in_progress)
+ * - block: WU blocked (transitions to blocked)
+ * - unblock: WU unblocked (transitions back to in_progress)
+ * - complete: WU completed (transitions to done)
+ * - checkpoint: Progress checkpoint (WU-1748: cross-agent visibility)
+ * - spawn: WU spawned from parent (WU-1947: parent-child relationships)
+ */
+export declare const WU_EVENT_TYPES: readonly ["create", "claim", "block", "unblock", "complete", "checkpoint", "spawn"];
+/** Type for WU event types */
+export type WUEventType = (typeof WU_EVENT_TYPES)[number];
+/**
+ * WU status values (matches LumenFlow state machine)
+ */
+export declare const WU_STATUSES: readonly ["ready", "in_progress", "blocked", "waiting", "done"];
+/** Type for WU status values */
+export type WUStatus = (typeof WU_STATUSES)[number];
+/**
+ * Regex patterns for WU validation
+ */
+export declare const WU_PATTERNS: {
+    /** WU ID format: WU-{digits} */
+    WU_ID: RegExp;
+};
+/**
+ * Create event schema
+ */
+export declare const CreateEventSchema: z.ZodObject<{
+    wuId: z.ZodString;
+    timestamp: z.ZodString;
+    type: z.ZodLiteral<"create">;
+    lane: z.ZodString;
+    title: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Claim event schema
+ */
+export declare const ClaimEventSchema: z.ZodObject<{
+    wuId: z.ZodString;
+    timestamp: z.ZodString;
+    type: z.ZodLiteral<"claim">;
+    lane: z.ZodString;
+    title: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Block event schema
+ */
+export declare const BlockEventSchema: z.ZodObject<{
+    wuId: z.ZodString;
+    timestamp: z.ZodString;
+    type: z.ZodLiteral<"block">;
+    reason: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Unblock event schema
+ */
+export declare const UnblockEventSchema: z.ZodObject<{
+    wuId: z.ZodString;
+    timestamp: z.ZodString;
+    type: z.ZodLiteral<"unblock">;
+}, z.core.$strip>;
+/**
+ * Complete event schema
+ */
+export declare const CompleteEventSchema: z.ZodObject<{
+    wuId: z.ZodString;
+    timestamp: z.ZodString;
+    type: z.ZodLiteral<"complete">;
+}, z.core.$strip>;
+/**
+ * Checkpoint event schema (WU-1748: cross-agent visibility)
+ * Records progress checkpoints for abandoned WU detection
+ */
+export declare const CheckpointEventSchema: z.ZodObject<{
+    wuId: z.ZodString;
+    timestamp: z.ZodString;
+    type: z.ZodLiteral<"checkpoint">;
+    note: z.ZodString;
+    sessionId: z.ZodOptional<z.ZodString>;
+    progress: z.ZodOptional<z.ZodString>;
+    nextSteps: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Spawn event schema (WU-1947: parent-child relationships)
+ * Records WU spawn relationships for tracking parent-child WUs
+ */
+export declare const SpawnEventSchema: z.ZodObject<{
+    wuId: z.ZodString;
+    timestamp: z.ZodString;
+    type: z.ZodLiteral<"spawn">;
+    parentWuId: z.ZodString;
+    spawnId: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Union schema for all event types
+ */
+export declare const WUEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    wuId: z.ZodString;
+    timestamp: z.ZodString;
+    type: z.ZodLiteral<"create">;
+    lane: z.ZodString;
+    title: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    wuId: z.ZodString;
+    timestamp: z.ZodString;
+    type: z.ZodLiteral<"claim">;
+    lane: z.ZodString;
+    title: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    wuId: z.ZodString;
+    timestamp: z.ZodString;
+    type: z.ZodLiteral<"block">;
+    reason: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    wuId: z.ZodString;
+    timestamp: z.ZodString;
+    type: z.ZodLiteral<"unblock">;
+}, z.core.$strip>, z.ZodObject<{
+    wuId: z.ZodString;
+    timestamp: z.ZodString;
+    type: z.ZodLiteral<"complete">;
+}, z.core.$strip>, z.ZodObject<{
+    wuId: z.ZodString;
+    timestamp: z.ZodString;
+    type: z.ZodLiteral<"checkpoint">;
+    note: z.ZodString;
+    sessionId: z.ZodOptional<z.ZodString>;
+    progress: z.ZodOptional<z.ZodString>;
+    nextSteps: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    wuId: z.ZodString;
+    timestamp: z.ZodString;
+    type: z.ZodLiteral<"spawn">;
+    parentWuId: z.ZodString;
+    spawnId: z.ZodString;
+}, z.core.$strip>], "type">;
+/**
+ * TypeScript types inferred from schemas
+ */
+export type CreateEvent = z.infer<typeof CreateEventSchema>;
+export type ClaimEvent = z.infer<typeof ClaimEventSchema>;
+export type BlockEvent = z.infer<typeof BlockEventSchema>;
+export type UnblockEvent = z.infer<typeof UnblockEventSchema>;
+export type CompleteEvent = z.infer<typeof CompleteEventSchema>;
+export type CheckpointEvent = z.infer<typeof CheckpointEventSchema>;
+export type SpawnEvent = z.infer<typeof SpawnEventSchema>;
+export type WUEvent = z.infer<typeof WUEventSchema>;
+/**
+ * Validates WU event data against schema
+ *
+ * @param {unknown} data - Data to validate
+ * @returns {z.SafeParseReturnType<WUEvent, WUEvent>} Validation result
+ *
+ * @example
+ * const result = validateWUEvent(eventData);
+ * if (!result.success) {
+ *   result.error.issues.forEach(issue => {
+ *     console.error(`${issue.path.join('.')}: ${issue.message}`);
+ *   });
+ * }
+ */
+export declare function validateWUEvent(data: any): z.ZodSafeParseResult<{
+    wuId: string;
+    timestamp: string;
+    type: "create";
+    lane: string;
+    title: string;
+} | {
+    wuId: string;
+    timestamp: string;
+    type: "claim";
+    lane: string;
+    title: string;
+} | {
+    wuId: string;
+    timestamp: string;
+    type: "block";
+    reason: string;
+} | {
+    wuId: string;
+    timestamp: string;
+    type: "unblock";
+} | {
+    wuId: string;
+    timestamp: string;
+    type: "complete";
+} | {
+    wuId: string;
+    timestamp: string;
+    type: "checkpoint";
+    note: string;
+    sessionId?: string;
+    progress?: string;
+    nextSteps?: string;
+} | {
+    wuId: string;
+    timestamp: string;
+    type: "spawn";
+    parentWuId: string;
+    spawnId: string;
+}>;

package/dist/wu-state-schema.js

@@ -0,0 +1,156 @@
+/**
+ * WU State Schema (WU-1570)
+ *
+ * Zod schemas for WU state event validation.
+ * Defines event types for WU lifecycle: create, claim, block, unblock, complete.
+ *
+ * @see {@link tools/lib/__tests__/wu-state-store.test.mjs} - Tests
+ */
+import { z } from 'zod';
+/**
+ * WU event types
+ *
+ * - create: WU created (transitions to ready)
+ * - claim: WU claimed (transitions to in_progress)
+ * - block: WU blocked (transitions to blocked)
+ * - unblock: WU unblocked (transitions back to in_progress)
+ * - complete: WU completed (transitions to done)
+ * - checkpoint: Progress checkpoint (WU-1748: cross-agent visibility)
+ * - spawn: WU spawned from parent (WU-1947: parent-child relationships)
+ */
+export const WU_EVENT_TYPES = [
+    'create',
+    'claim',
+    'block',
+    'unblock',
+    'complete',
+    'checkpoint',
+    'spawn',
+];
+/**
+ * WU status values (matches LumenFlow state machine)
+ */
+export const WU_STATUSES = ['ready', 'in_progress', 'blocked', 'waiting', 'done'];
+/**
+ * Regex patterns for WU validation
+ */
+export const WU_PATTERNS = {
+    /** WU ID format: WU-{digits} */
+    WU_ID: /^WU-\d+$/,
+};
+/**
+ * Error messages for schema validation
+ */
+const ERROR_MESSAGES = {
+    EVENT_TYPE: `Event type must be one of: ${WU_EVENT_TYPES.join(', ')}`,
+    WU_ID: 'WU ID must match pattern WU-XXX (e.g., WU-1570)',
+    LANE_REQUIRED: 'Lane is required',
+    TITLE_REQUIRED: 'Title is required',
+    REASON_REQUIRED: 'Reason is required',
+    TIMESTAMP_REQUIRED: 'Timestamp is required',
+};
+/**
+ * Base event schema (common fields for all events)
+ */
+const BaseEventSchema = z.object({
+    /** Event type */
+    type: z.enum(WU_EVENT_TYPES, {
+        error: ERROR_MESSAGES.EVENT_TYPE,
+    }),
+    /** WU ID */
+    wuId: z.string().regex(WU_PATTERNS.WU_ID, { message: ERROR_MESSAGES.WU_ID }),
+    /** Event timestamp (ISO 8601 datetime) */
+    timestamp: z.string().datetime({ message: ERROR_MESSAGES.TIMESTAMP_REQUIRED }),
+});
+/**
+ * Create event schema
+ */
+export const CreateEventSchema = BaseEventSchema.extend({
+    type: z.literal('create'),
+    lane: z.string().min(1, { message: ERROR_MESSAGES.LANE_REQUIRED }),
+    title: z.string().min(1, { message: ERROR_MESSAGES.TITLE_REQUIRED }),
+});
+/**
+ * Claim event schema
+ */
+export const ClaimEventSchema = BaseEventSchema.extend({
+    type: z.literal('claim'),
+    lane: z.string().min(1, { message: ERROR_MESSAGES.LANE_REQUIRED }),
+    title: z.string().min(1, { message: ERROR_MESSAGES.TITLE_REQUIRED }),
+});
+/**
+ * Block event schema
+ */
+export const BlockEventSchema = BaseEventSchema.extend({
+    type: z.literal('block'),
+    reason: z.string().min(1, { message: ERROR_MESSAGES.REASON_REQUIRED }),
+});
+/**
+ * Unblock event schema
+ */
+export const UnblockEventSchema = BaseEventSchema.extend({
+    type: z.literal('unblock'),
+});
+/**
+ * Complete event schema
+ */
+export const CompleteEventSchema = BaseEventSchema.extend({
+    type: z.literal('complete'),
+});
+/**
+ * Checkpoint event schema (WU-1748: cross-agent visibility)
+ * Records progress checkpoints for abandoned WU detection
+ */
+export const CheckpointEventSchema = BaseEventSchema.extend({
+    type: z.literal('checkpoint'),
+    /** Checkpoint note/description */
+    note: z.string().min(1, { message: 'Checkpoint note is required' }),
+    /** Optional session ID */
+    sessionId: z.string().optional(),
+    /** Optional progress summary */
+    progress: z.string().optional(),
+    /** Optional next steps */
+    nextSteps: z.string().optional(),
+});
+/**
+ * Spawn event schema (WU-1947: parent-child relationships)
+ * Records WU spawn relationships for tracking parent-child WUs
+ */
+export const SpawnEventSchema = BaseEventSchema.extend({
+    type: z.literal('spawn'),
+    /** Parent WU ID that spawned this WU */
+    parentWuId: z
+        .string()
+        .regex(WU_PATTERNS.WU_ID, { message: 'Parent WU ID must match pattern WU-XXX' }),
+    /** Unique spawn identifier */
+    spawnId: z.string().min(1, { message: 'Spawn ID is required' }),
+});
+/**
+ * Union schema for all event types
+ */
+export const WUEventSchema = z.discriminatedUnion('type', [
+    CreateEventSchema,
+    ClaimEventSchema,
+    BlockEventSchema,
+    UnblockEventSchema,
+    CompleteEventSchema,
+    CheckpointEventSchema,
+    SpawnEventSchema,
+]);
+/**
+ * Validates WU event data against schema
+ *
+ * @param {unknown} data - Data to validate
+ * @returns {z.SafeParseReturnType<WUEvent, WUEvent>} Validation result
+ *
+ * @example
+ * const result = validateWUEvent(eventData);
+ * if (!result.success) {
+ *   result.error.issues.forEach(issue => {
+ *     console.error(`${issue.path.join('.')}: ${issue.message}`);
+ *   });
+ * }
+ */
+export function validateWUEvent(data) {
+    return WUEventSchema.safeParse(data);
+}

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

@@ -0,0 +1,264 @@
+/**
+ * WU State Store (WU-1570, WU-2240)
+ *
+ * Event-sourced state store for WU lifecycle following INIT-007 pattern.
+ * Stores events in .beacon/state/wu-events.jsonl (append-only, git-friendly).
+ *
+ * Features:
+ * - Event sourcing with replay for current state
+ * - Atomic append operations (WU-2240: temp file + fsync + rename)
+ * - O(1) queries by status and lane via in-memory indexes
+ * - State machine validation for legal transitions
+ * - File locking with stale detection (WU-2240)
+ * - Corruption recovery via repairStateFile (WU-2240)
+ *
+ * @see {@link tools/__tests__/state-store-concurrent.test.mjs} - Concurrent access tests
+ * @see {@link tools/lib/wu-state-schema.mjs} - Schema definitions
+ */
+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);
+    /**
+     * 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:status'
+     * });
+     */
+    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 spawned 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 spawn relationship between parent and child WUs.
+     * WU-1947: Parent-child relationship tracking.
+     *
+     * @example
+     * await store.spawn('WU-200', 'WU-100', 'spawn-abc123');
+     */
+    spawn(childWuId: string, parentWuId: string, spawnId: string): Promise<void>;
+}
+/**
+ * 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(), '.beacon', '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>;