@lumenflow/core 3.1.3 → 3.2.1

package/dist/ports/metrics-collector.port.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Metrics Collector Port
+ *
+ * Hexagonal Architecture - Input Port
+ * Defines the contract for collecting orchestration metrics from various sources.
+ * This abstraction allows the application layer to remain independent of
+ * specific data sources (filesystem, database, API, etc.).
+ *
+ * Current Implementations:
+ * - FileSystemMetricsCollector (WU-1321) - Reads WU YAML, status.md, telemetry
+ *
+ * Future Implementations:
+ * - DatabaseMetricsCollector - Query from Supabase
+ * - APIMetricsCollector - Fetch from external service
+ * - MockMetricsCollector - Testing purposes
+ *
+ * SOLID Principles:
+ * - Dependency Inversion: Use cases depend on this abstraction, not concrete collectors
+ * - Interface Segregation: Each method has a single responsibility
+ * - Open/Closed: New collectors can be added without modifying existing code
+ *
+ * @module metrics-collector.port
+ * @see {@link ../domain/orchestration.types.ts} - Types returned by this interface
+ * @see {@link ../../adapters/filesystem-metrics.adapter.ts} - Filesystem implementation (WU-1321)
+ */
+import type { GlobalStatus, AgentMetric, WUProgress, TimelineEvent, Alert } from '../domain/orchestration.types.js';
+/**
+ * Metrics Collector Port Interface
+ *
+ * Implementers must provide methods to collect all metrics needed
+ * for dashboard rendering. Each method should be independently callable
+ * to allow selective data fetching.
+ *
+ * @example
+ * // Implementing a custom collector
+ * class CustomCollector implements IMetricsCollector {
+ *   async getGlobalStatus(): Promise<GlobalStatus> {
+ *     // Collect active WUs, completed count, blocked count, etc.
+ *   }
+ *
+ *   async getAgentMetrics(): Promise<Record<string, AgentMetric>> {
+ *     // Collect per-agent invocation counts, pass rates, timing
+ *   }
+ *
+ *   // ... other methods
+ * }
+ *
+ * @example
+ * // Using in a use case
+ * class GetDashboardDataUseCase {
+ *   constructor(private readonly collector: IMetricsCollector) {}
+ *
+ *   async execute(): Promise<DashboardData> {
+ *     const [globalStatus, agentMetrics, wuProgress, timeline, alerts] =
+ *       await Promise.all([
+ *         this.collector.getGlobalStatus(),
+ *         this.collector.getAgentMetrics(),
+ *         this.collector.getWUProgress(),
+ *         this.collector.getTimeline(this.since24h()),
+ *         this.collector.getAlerts(),
+ *       ]);
+ *
+ *     return { globalStatus, agentMetrics, wuProgress, timeline, alerts };
+ *   }
+ * }
+ */
+export interface IMetricsCollector {
+    /**
+     * Get global orchestration status.
+     *
+     * Should aggregate:
+     * - Count of WUs in 'in_progress' state
+     * - Count of WUs completed in last 24 hours
+     * - Count of currently blocked WUs
+     * - Count of WUs with failing gates
+     * - Longest running WU information
+     * - List of WUs with pending mandatory agents
+     *
+     * @returns Global status metrics
+     */
+    getGlobalStatus(): Promise<GlobalStatus>;
+    /**
+     * Get metrics for all known agents.
+     *
+     * Should collect for each agent:
+     * - Total invocation count
+     * - Pass rate (percentage)
+     * - Average duration in milliseconds
+     * - Information about most recent run
+     *
+     * @returns Record mapping agent names to their metrics
+     */
+    getAgentMetrics(): Promise<Record<string, AgentMetric>>;
+    /**
+     * Get progress for all active WUs.
+     *
+     * Should collect for each active WU:
+     * - WU ID and title
+     * - Lane assignment
+     * - DoD checkpoint progress
+     * - Agent run statuses
+     * - Headline sentence (Tufte principle)
+     *
+     * @returns Array of WU progress records, sorted by lane then WU ID
+     */
+    getWUProgress(): Promise<WUProgress[]>;
+    /**
+     * Get timeline events since a given date.
+     *
+     * Should collect events of types:
+     * - claim: WU claimed
+     * - done: WU completed
+     * - block: WU blocked
+     * - agent: Agent invoked with result
+     * - gates: Gates run with result
+     *
+     * @param since - Only return events after this timestamp
+     * @returns Array of timeline events, sorted by timestamp descending
+     */
+    getTimeline(since: Date): Promise<TimelineEvent[]>;
+    /**
+     * Get current alerts requiring attention.
+     *
+     * Should generate alerts for:
+     * - Mandatory agents not yet invoked (HIGH)
+     * - WUs near completion needing review (MEDIUM)
+     * - Available lanes with ready WUs (LOW)
+     *
+     * @returns Array of alerts, sorted by severity (high first)
+     */
+    getAlerts(): Promise<Alert[]>;
+}
+//# sourceMappingURL=metrics-collector.port.d.ts.map

package/dist/ports/metrics-collector.port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-collector.port.d.ts","sourceRoot":"","sources":["../../src/ports/metrics-collector.port.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,UAAU,EACV,aAAa,EACb,KAAK,EACN,MAAM,kCAAkC,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;;;OAYG;IACH,eAAe,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzC;;;;;;;;;;OAUG;IACH,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IAExD;;;;;;;;;;;OAWG;IACH,aAAa,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAEvC;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAEnD;;;;;;;;;OASG;IACH,SAAS,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;CAC/B"}

package/dist/ports/metrics-collector.port.js

@@ -0,0 +1,4 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+export {};
+//# sourceMappingURL=metrics-collector.port.js.map

package/dist/ports/metrics-collector.port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-collector.port.js","sourceRoot":"","sources":["../../src/ports/metrics-collector.port.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC"}

package/dist/ports/recovery.ports.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Recovery Ports
+ *
+ * WU-1093: INIT-002 Phase 1 - Define ports and domain schemas
+ *
+ * Port interfaces for recovery-related operations.
+ * These abstractions allow external users to inject custom implementations.
+ *
+ * Hexagonal Architecture - Input Ports:
+ * - IRecoveryAnalyzer: Analyze WU state issues and suggest recovery actions
+ *
+ * Current Implementations:
+ * - analyzeRecovery (recovery-analyzer.ts)
+ *
+ * @module ports/recovery
+ */
+import type { WuContext } from '../validation/types.js';
+import type { RecoveryAnalysis } from '../recovery/recovery-analyzer.js';
+/**
+ * Recovery Analyzer Port Interface
+ *
+ * Analyzes WU context to detect state inconsistencies and suggests
+ * appropriate recovery actions.
+ *
+ * Issue types detected:
+ * - Partial claim: worktree exists but status is ready
+ * - Orphan claim: status is in_progress but worktree missing
+ * - Inconsistent state: YAML and state store disagree
+ * - Orphan branch: branch exists but worktree missing
+ * - Stale lock: lock file from old session
+ * - Leftover worktree: WU is done but worktree exists
+ *
+ * @example
+ * // Custom implementation for testing
+ * const mockAnalyzer: IRecoveryAnalyzer = {
+ *   analyzeRecovery: async (context) => ({
+ *     hasIssues: false,
+ *     issues: [],
+ *     actions: [],
+ *     wuId: context.wu?.id ?? null,
+ *   }),
+ * };
+ *
+ * @example
+ * // Using default implementation
+ * import { analyzeRecovery } from './recovery/recovery-analyzer.js';
+ * const analyzer: IRecoveryAnalyzer = { analyzeRecovery };
+ */
+export interface IRecoveryAnalyzer {
+    /**
+     * Analyze context for recovery issues.
+     *
+     * @param context - Current WU context
+     * @returns Promise<RecoveryAnalysis> - Recovery analysis with issues and suggested actions
+     */
+    analyzeRecovery(context: WuContext): Promise<RecoveryAnalysis>;
+}
+export type { WuContext, RecoveryAnalysis };
+//# sourceMappingURL=recovery.ports.d.ts.map

package/dist/ports/recovery.ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.ports.d.ts","sourceRoot":"","sources":["../../src/ports/recovery.ports.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,eAAe,CAAC,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAChE;AAGD,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/ports/recovery.ports.js

@@ -0,0 +1,4 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+export {};
+//# sourceMappingURL=recovery.ports.js.map

package/dist/ports/recovery.ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.ports.js","sourceRoot":"","sources":["../../src/ports/recovery.ports.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC"}

package/dist/ports/validation.ports.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Validation Ports
+ *
+ * WU-1093: INIT-002 Phase 1 - Define ports and domain schemas
+ *
+ * Port interfaces for validation-related operations.
+ * These abstractions allow external users to inject custom implementations.
+ *
+ * Hexagonal Architecture - Input Ports:
+ * - ICommandRegistry: Lookup command definitions and validate commands
+ *
+ * Current Implementations:
+ * - COMMAND_REGISTRY, getCommandDefinition, getValidCommandsForContext (command-registry.ts)
+ *
+ * @module ports/validation
+ */
+import type { CommandDefinition, WuContext } from '../validation/types.js';
+/**
+ * Command Registry Port Interface
+ *
+ * Provides command definitions and validation logic for wu:* commands.
+ * Allows looking up command requirements and determining valid commands
+ * for a given context.
+ *
+ * @example
+ * // Custom implementation for testing
+ * const mockRegistry: ICommandRegistry = {
+ *   getCommandDefinition: (cmd) => cmd === 'wu:done' ? {...} : null,
+ *   getValidCommandsForContext: (ctx) => [...],
+ *   getAllCommands: () => [...],
+ * };
+ *
+ * @example
+ * // Using default implementation
+ * import {
+ *   getCommandDefinition,
+ *   getValidCommandsForContext,
+ *   COMMAND_REGISTRY,
+ * } from './validation/command-registry.js';
+ *
+ * const registry: ICommandRegistry = {
+ *   getCommandDefinition,
+ *   getValidCommandsForContext,
+ *   getAllCommands: () => Array.from(COMMAND_REGISTRY.values()),
+ * };
+ */
+export interface ICommandRegistry {
+    /**
+     * Get command definition by name.
+     *
+     * @param command - Command name (e.g., 'wu:create', 'wu:done')
+     * @returns CommandDefinition or null if not found
+     */
+    getCommandDefinition(command: string): CommandDefinition | null;
+    /**
+     * Get all commands valid for the current context.
+     *
+     * A command is valid if:
+     * - Location requirement is satisfied (or null = UnsafeAny)
+     * - WU status requirement is satisfied (or null = no WU required)
+     * - All error-severity predicates pass
+     *
+     * @param context - Current WU context
+     * @returns Array of valid CommandDefinitions
+     */
+    getValidCommandsForContext(context: WuContext): CommandDefinition[];
+    /**
+     * Get all registered command definitions.
+     *
+     * @returns Array of all CommandDefinitions
+     */
+    getAllCommands(): CommandDefinition[];
+}
+export type { CommandDefinition, WuContext };
+//# sourceMappingURL=validation.ports.d.ts.map

package/dist/ports/validation.ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.ports.d.ts","sourceRoot":"","sources":["../../src/ports/validation.ports.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAAC;IAEhE;;;;;;;;;;OAUG;IACH,0BAA0B,CAAC,OAAO,EAAE,SAAS,GAAG,iBAAiB,EAAE,CAAC;IAEpE;;;;OAIG;IACH,cAAc,IAAI,iBAAiB,EAAE,CAAC;CACvC;AAGD,YAAY,EAAE,iBAAiB,EAAE,SAAS,EAAE,CAAC"}

package/dist/ports/validation.ports.js

@@ -0,0 +1,4 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+export {};
+//# sourceMappingURL=validation.ports.js.map

package/dist/ports/validation.ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.ports.js","sourceRoot":"","sources":["../../src/ports/validation.ports.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC"}

package/dist/ports/wu-helpers.ports.d.ts

@@ -0,0 +1,168 @@
+/**
+ * WU Helpers Port Interfaces
+ *
+ * WU-1102: INIT-003 Phase 2b - Port interfaces for WU helper modules
+ *
+ * Hexagonal Architecture - Input Ports:
+ * These abstractions allow external users to inject custom implementations
+ * for WU lifecycle operations.
+ *
+ * @module ports/wu-helpers
+ */
+/**
+ * Git adapter interface for ensureOnMain and ensureMainUpToDate operations
+ */
+export interface IWuGitAdapter {
+    /**
+     * Get the current git branch name
+     * @returns Promise resolving to branch name
+     */
+    getCurrentBranch(): Promise<string>;
+    /**
+     * Fetch from a remote
+     * @param remote - Remote name (e.g., 'origin')
+     * @param branch - Branch name (e.g., 'main')
+     */
+    fetch(remote: string, branch: string): Promise<void>;
+    /**
+     * Get commit hash for a ref
+     * @param ref - Git ref (branch, tag, or commit)
+     * @returns Promise resolving to commit hash
+     */
+    getCommitHash(ref: string): Promise<string>;
+}
+/**
+ * WU status check result
+ */
+export interface IWuStatusCheckResult {
+    /** Whether the operation is allowed */
+    allowed: boolean;
+    /** Current WU status */
+    status: string | null;
+    /** Error message if not allowed */
+    error: string | null;
+}
+/**
+ * Branch validation result
+ */
+export interface IBranchValidationResult {
+    /** Whether the branch name is valid */
+    valid: boolean;
+    /** Lane name (kebab-case) or null */
+    lane: string | null;
+    /** WU ID (uppercase) or null */
+    wuid: string | null;
+    /** Error message if invalid */
+    error: string | null;
+}
+/**
+ * WU YAML reader interface
+ */
+export interface IWuYamlReader {
+    /**
+     * Read and parse WU YAML file
+     * @param wuPath - Path to WU YAML file
+     * @param expectedId - Expected WU ID for validation
+     * @returns Parsed WU document
+     */
+    readWU(wuPath: string, expectedId: string): unknown;
+    /**
+     * Read YAML file without ID validation
+     * @param yamlPath - Path to YAML file
+     * @returns Parsed document
+     */
+    readWURaw(yamlPath: string): unknown;
+}
+/**
+ * WU YAML writer interface
+ */
+export interface IWuYamlWriter {
+    /**
+     * Write WU document to file
+     * @param wuPath - Path to WU YAML file
+     * @param doc - Document to write
+     */
+    writeWU(wuPath: string, doc: unknown): void;
+}
+export type { IWuStateStore } from './wu-state.ports.js';
+/**
+ * WU checkpoint interface
+ */
+export interface IWuCheckpointManager {
+    /**
+     * Create a pre-gates checkpoint
+     */
+    createPreGatesCheckpoint(params: {
+        wuId: string;
+        worktreePath: string;
+        branchName: string;
+        gatesPassed?: boolean;
+    }, options?: {
+        baseDir?: string;
+    }): Promise<{
+        checkpointId: string;
+        gatesPassed: boolean;
+    }>;
+    /**
+     * Mark checkpoint as gates passed
+     * @param wuId - WU identifier
+     * @returns True if updated
+     */
+    markGatesPassed(wuId: string, options?: {
+        baseDir?: string;
+    }): boolean;
+    /**
+     * Get checkpoint for a WU
+     * @param wuId - WU identifier
+     * @returns Checkpoint or null
+     */
+    getCheckpoint(wuId: string, options?: {
+        baseDir?: string;
+    }): {
+        gatesPassed: boolean;
+        worktreeHeadSha: string;
+    } | null;
+    /**
+     * Clear checkpoint
+     * @param wuId - WU identifier
+     */
+    clearCheckpoint(wuId: string, options?: {
+        baseDir?: string;
+    }): void;
+    /**
+     * Check if gates can be skipped
+     */
+    canSkipGates(wuId: string, options?: {
+        baseDir?: string;
+        currentHeadSha?: string;
+    }): {
+        canSkip: boolean;
+        reason?: string;
+    };
+}
+/**
+ * WU paths interface
+ */
+export interface IWuPaths {
+    /** Get path to WU YAML file */
+    WU(id: string): string;
+    /** Get path to WU directory */
+    WU_DIR(): string;
+    /** Get path to status.md */
+    STATUS(): string;
+    /** Get path to backlog.md */
+    BACKLOG(): string;
+    /** Get path to stamps directory */
+    STAMPS_DIR(): string;
+    /** Get path to WU done stamp file */
+    STAMP(id: string): string;
+    /** Get path to state directory */
+    STATE_DIR(): string;
+    /** Get path to initiatives directory */
+    INITIATIVES_DIR(): string;
+    /** Get path to initiative YAML file */
+    INITIATIVE(id: string): string;
+    /** Get path to worktrees directory */
+    WORKTREES_DIR(): string;
+}
+//# sourceMappingURL=wu-helpers.ports.d.ts.map

package/dist/ports/wu-helpers.ports.d.ts.map

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

package/dist/ports/wu-helpers.ports.js

@@ -0,0 +1,4 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+export {};
+//# sourceMappingURL=wu-helpers.ports.js.map

package/dist/ports/wu-helpers.ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wu-helpers.ports.js","sourceRoot":"","sources":["../../src/ports/wu-helpers.ports.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC"}

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

@@ -0,0 +1,190 @@
+/**
+ * WU State Ports (WU-2013)
+ *
+ * Focused interfaces for the decomposed WU state store services.
+ * Each interface defines a single responsibility boundary.
+ *
+ * @module ports/wu-state
+ */
+import type { WUEvent } from '../wu-state-schema.js';
+/**
+ * WU state entry in the in-memory store
+ */
+export interface WUStateEntry {
+    status: string;
+    lane: string;
+    title: string;
+    completedAt?: string;
+    lastCheckpoint?: string;
+    lastCheckpointNote?: string;
+}
+/**
+ * Checkpoint options for recording WU progress
+ */
+export interface CheckpointOptions {
+    sessionId?: string;
+    progress?: string;
+    nextSteps?: string;
+}
+/**
+ * Lock file data structure
+ */
+export interface LockData {
+    pid: number;
+    timestamp: number;
+    hostname: string;
+}
+/**
+ * Repair result from corruption recovery
+ */
+export interface RepairResult {
+    success: boolean;
+    linesKept: number;
+    linesRemoved: number;
+    backupPath: string | null;
+    warnings: string[];
+}
+/**
+ * Event log interface for loading, replaying, and appending WU events.
+ *
+ * Responsible for:
+ * - Loading events from JSONL storage
+ * - Replaying events to rebuild in-memory state
+ * - Appending new validated events
+ * - Running delegation cutover migration
+ */
+export interface IWuEventLog {
+    /**
+     * Load and replay events from storage into in-memory state.
+     * Resets all state before replaying.
+     */
+    load(): Promise<void>;
+    /**
+     * Append a validated event to persistent storage and apply to in-memory state.
+     */
+    appendAndApply(event: WUEvent): Promise<void>;
+    /**
+     * Apply a validated event to in-memory state without persisting.
+     */
+    applyEvent(event: WUEvent): void;
+}
+/**
+ * Lock manager interface for file-level locking with stale detection.
+ *
+ * Responsible for:
+ * - Acquiring file locks with retry logic
+ * - Releasing file locks
+ * - Detecting stale locks (expired or dead process)
+ */
+export interface IWuLockManager {
+    /**
+     * Acquire a file lock at the given path.
+     * Retries with stale lock detection.
+     *
+     * @throws Error if lock cannot be acquired after retries
+     */
+    acquireLock(lockPath: string): Promise<void>;
+    /**
+     * Release a file lock at the given path.
+     * Silently ignores errors if lock file doesn't exist.
+     */
+    releaseLock(lockPath: string): void;
+    /**
+     * Check if a lock is stale (expired timeout or dead process).
+     */
+    isLockStale(lockData: LockData): boolean;
+}
+/**
+ * State query interface for O(1) lookups into WU state.
+ *
+ * Responsible for:
+ * - Querying WU state by ID
+ * - Querying WU IDs by status (O(1))
+ * - Querying WU IDs by lane (O(1))
+ * - Querying child WU IDs by parent (O(1))
+ */
+export interface IWuStateQuery {
+    /**
+     * Get current in-memory state for a WU.
+     */
+    getWUState(wuId: string): WUStateEntry | undefined;
+    /**
+     * Get WU IDs by status (O(1) lookup).
+     */
+    getByStatus(status: string): Set<string>;
+    /**
+     * Get WU IDs by lane (O(1) lookup).
+     */
+    getByLane(lane: string): Set<string>;
+    /**
+     * Get child WU IDs delegated from a parent WU (O(1) lookup).
+     */
+    getChildWUs(parentWuId: string): Set<string>;
+}
+/**
+ * WU State Store interface for dependency injection in command handlers.
+ *
+ * Combines event log and state query capabilities into a single injectable
+ * interface. Command handlers should depend on this interface rather than
+ * importing and instantiating WUStateStore directly.
+ *
+ * WU-2020: DIP compliance - high-level modules depend on abstraction,
+ * not on the concrete WUStateStore class.
+ *
+ * @example
+ * ```typescript
+ * // Command handler accepts interface, not concrete class
+ * async function completeWU(store: IWuStateStore, wuId: string) {
+ *   await store.load();
+ *   await store.complete(wuId);
+ * }
+ * ```
+ */
+export interface IWuStateStore extends IWuEventLog, IWuStateQuery {
+    /**
+     * Claim a WU, transitioning it to in_progress status.
+     * @throws Error if WU is already in_progress
+     */
+    claim(wuId: string, lane: string, title: string): Promise<void>;
+    /**
+     * Complete a WU, transitioning it to done status.
+     * @throws Error if WU is not in_progress
+     */
+    complete(wuId: string): Promise<void>;
+    /**
+     * Block a WU with a reason.
+     * @throws Error if WU is not in_progress
+     */
+    block(wuId: string, reason: string): Promise<void>;
+    /**
+     * Unblock a WU, transitioning it back to in_progress.
+     * @throws Error if WU is not blocked
+     */
+    unblock(wuId: string): Promise<void>;
+    /**
+     * Record a checkpoint for a WU without changing its status.
+     */
+    checkpoint(wuId: string, note: string, options?: CheckpointOptions): Promise<void>;
+    /**
+     * Record a parent-child delegation relationship.
+     */
+    delegate(childWuId: string, parentWuId: string, delegationId: string): Promise<void>;
+    /**
+     * Release a WU, transitioning it from in_progress to ready.
+     * @throws Error if WU is not in_progress
+     */
+    release(wuId: string, reason: string): Promise<void>;
+    /**
+     * Create a complete event without persisting it.
+     * Useful for transactional flows.
+     * @throws Error if WU is not in_progress
+     */
+    createCompleteEvent(wuId: string, timestamp?: string): WUEvent;
+    /**
+     * Create a release event without persisting it.
+     * Useful for transactional flows.
+     * @throws Error if WU is not in_progress
+     */
+    createReleaseEvent(wuId: string, reason: string, timestamp?: string): WUEvent;
+}
+//# sourceMappingURL=wu-state.ports.d.ts.map