riksdagsmonitor 0.8.23 → 0.8.24

package/dist/scripts/workflow-state-coordinator.d.ts

@@ -1,354 +0,0 @@
-#!/usr/bin/env node
-/**
- * @module Infrastructure/WorkflowOrchestration
- * @category Infrastructure
- *
- * @title Workflow State Coordinator - Multi-Workflow Synchronization Engine
- *
- * @description
- * **INTELLIGENCE OPERATIVE PERSPECTIVE**
- *
- * This module orchestrates coordination between three independent news generation
- * workflows operating on different schedules, preventing wasted computational
- * resources on duplicate article generation and maintaining editorial consistency.
- * In intelligence operations, workflow state management prevents information
- * redundancy and ensures efficient use of computational and editorial resources.
- *
- * **WORKFLOW ARCHITECTURE:**
- * The platform operates three independent content generation workflows:
- *
- * 1. **Realtime Monitor (news-realtime-monitor.md)**
- *    Schedule: 2x daily (morning + afternoon)
- *    Content: Event-driven breaking news, voting updates, crisis response
- *    Intelligence value: Rapid notification of parliamentary surprises
- *    Latency: Real-time (5-15 minute response to events)
- *
- * 2. **Evening Analysis (news-evening-analysis.md)**
- *    Schedule: Daily at 17:00 (5 PM Swedish time)
- *    Content: Deep analytical synthesis, international context, forward assessment
- *    Intelligence value: End-of-day intelligence briefing format
- *    Latency: Structured analysis (1-2 hour research + writing)
- *
- * 3. **Article Generators (news-article-generator.md)**
- *    Schedule: Variable (triggered by content calendar or on-demand)
- *    Content: Committee reports, motions, propositions, week-ahead
- *    Intelligence value: Systematic coverage of all parliamentary products
- *    Latency: Scheduled batch processing (hourly to daily)
- *
- * **DEDUPLICATION FRAMEWORK:**
- * The coordinator prevents duplicate article generation using similarity analysis:
- *
- * - **Similarity Threshold: 70%**
- *   Computes Levenshtein distance on article titles and keyword sets
- *   Articles >70% similar are considered duplicates
- *   Prevents wasted generation of already-covered topics
- *
- * - **Time-Window Filtering: 6 hours**
- *   Checks if similar article was generated in last 6 hours
- *   Allows coverage of same topic if sufficient time has passed
- *   Prevents rapid-fire duplicates while allowing topic revisits
- *
- * - **Topic-Based Tracking**
- *   Logs article topics (votes, bills, committees, etc.)
- *   Enables intelligent filtering at generation time
- *   Supports trending topic analysis
- *
- * **MCP QUERY CACHING:**
- * To avoid redundant API calls to riksdag-regering MCP platform:
- *
- * - **Cache TTL: 2 hours**
- *   Stores results of expensive queries (voting patterns, full-text search)
- *   Reduces MCP server load during peak hours
- *   Ensures consistency across multiple workflow invocations
- *
- * - **Query Fingerprinting**
- *   Creates deterministic hash of MCP query parameters
- *   Enables cache hits even if queries structured differently
- *   Supports query normalization
- *
- * - **Staleness Handling**
- *   Fresh data (within 2 hours) used for analysis
- *   Older data triggers MCP refresh
- *   Prevents stale intelligence from being published
- *
- * **STATE MANAGEMENT:**
- * Persistent state file (news/metadata/workflow-state.json) tracks:
- * - Last workflow execution timestamp and results
- * - Recently generated articles (content + timestamp)
- * - MCP query cache with expiration times
- * - Workflow coordination metadata
- * - Running task list for cross-workflow visibility
- *
- * **OPERATIONAL WORKFLOW:**
- * 1. Workflow begins: Load current state from persistent storage
- * 2. Query Analysis: Check if similar article was recently generated
- * 3. Cache Check: Retrieve cached MCP queries if available (<2hr old)
- * 4. Generation: Create new article (or skip if duplicate)
- * 5. State Update: Log article and update cache
- * 6. Persistence: Write updated state for next workflow invocation
- *
- * **INCIDENT SCENARIOS:**
- * - **Double-Generation**: Realtime Monitor and Article Generator both cover voting
- *   Solution: Similarity detection blocks duplicate, tracks in state
- *
- * - **Stale Analysis**: Evening Analysis uses MCP data from morning
- *   Solution: 2-hour cache expiration triggers fresh queries
- *
- * - **Missed Coverage**: Topic isn't covered by any workflow
- *   Solution: State logs enable gap analysis, manual workflow triggers
- *
- * - **Cache Corruption**: Stale query results cause analytical errors
- *   Solution: TTL-based expiration automatically refreshes
- *
- * **INTELLIGENCE APPLICATIONS:**
- * - Prevents topic redundancy (editorial efficiency)
- * - Ensures consistent coverage across workflows
- * - Enables gap analysis (which topics are missed?)
- * - Supports workflow optimization (timing, triggers)
- * - Provides audit trail for editorial decisions
- *
- * **PERFORMANCE OPTIMIZATION:**
- * - MCP cache reduces API calls by estimated 60-70%
- * - Reduces computational load on MCP platform during peaks
- * - Faster generation cycles (cache lookups faster than API calls)
- * - Enables more frequent workflow execution
- *
- * **FAILURE MODES & RECOVERY:**
- * - State file corruption: Graceful fallback to generation without deduplication
- * - Cache miss during load: Automatic MCP refresh triggered
- * - Timestamp drift: UTC normalization prevents timezone confusion
- * - Concurrent workflow execution: Lock-based synchronization
- *
- * **SCALABILITY CONSIDERATIONS:**
- * - State file size grows ~50KB per month (manageable)
- * - Cache memory: ~5MB typical, scales with coverage breadth
- * - Similarity computation: O(n) in articles, automated pruning at 180 days
- * - MCP query cache: Automatic cleanup of expired entries
- *
- * **GDPR COMPLIANCE:**
- * - Member mentions in articles tracked in state
- * - Data retention policies enforced (180-day pruning)
- * - Audit trail supports member rights requests
- * - No personal data stored in cache beyond article references
- *
- * @osint Workflow Intelligence Analysis
- * - Tracks which topics get covered and when
- * - Identifies coordination patterns across workflows
- * - Enables predictive analysis of future coverage
- * - Supports investigation of coordination anomalies
- *
- * @risk Deduplication Accuracy
- * - 70% similarity threshold prevents false positives
- * - Enables legitimate retelling of same story (new angle)
- * - Detects coordinated coverage (unusual pattern)
- * - Monitors for suspicious generation patterns
- *
- * @gdpr Data Retention & Cleanup
- * - Automatic pruning of state after 180 days
- * - Member data retention tied to article dates
- * - Supports right-to-be-forgotten implementations
- * - Audit logging for regulatory compliance
- *
- * @security State Integrity
- * - File permissions protect state from unauthorized modification
- * - Checksums validate cache data integrity
- * - Atomic writes prevent partial state corruption
- * - Versioning enables rollback if needed
- *
- * @author Hack23 AB (Editorial Operations & Workflow Optimization)
- * @license Apache-2.0
- * @version 2.2.0
- * @since 2024-10-15
- * @see news/metadata/workflow-state.json (State Persistence)
- * @see Issue #150 (Workflow Coordination Enhancement)
- * @see docs/WORKFLOW_ARCHITECTURE.md (Complete Architecture)
- */
-import type { RecentArticleEntry, RecentArticleInput, DuplicateCheckResult, WorkflowExecutionMetadata, WorkflowStatistics, LockInfo, ActiveGeneration } from './types/workflow.js';
-declare const MCP_CACHE_TTL_SECONDS: number;
-declare const MCP_CACHE_TTL_NON_PLENARY_SECONDS: number;
-declare const RECENT_ARTICLE_TTL_SECONDS: number;
-declare const SIMILARITY_THRESHOLD: number;
-declare const TOPIC_JACCARD_THRESHOLD: number;
-declare const LOCK_TIMEOUT_MS: number;
-declare const ACTIVE_GENERATION_TTL_MS: number;
-/**
- * Compute Jaccard similarity between two topic arrays.
- *
- * @param a - First topic array
- * @param b - Second topic array
- * @returns Jaccard similarity 0.0-1.0
- */
-export declare function jaccardTopicSimilarity(a: string[], b: string[]): number;
-/**
- * Return adaptive MCP cache TTL based on Riksdag plenary hours.
- *
- * Plenary hours: 08:00–16:00 Europe/Stockholm local time (DST-aware) → 2-hour TTL.
- * Non-plenary hours → 4-hour TTL (data changes less frequently).
- *
- * @param now - Optional Date for testing
- * @returns TTL in seconds
- */
-export declare function getAdaptiveCacheTTL(now?: Date): number;
-/**
- * Workflow Lock Manager — file-based soft locks for cross-workflow coordination.
- *
- * Locks are directories under `news/metadata/locks/{type}-{date}.lock/`
- * containing an `info.json` file with lease metadata.
- */
-export declare class WorkflowLockManager {
-    private readonly lockDir;
-    private readonly timeoutMs;
-    constructor(lockDir?: string, timeoutMs?: number);
-    private validateLockInputs;
-    private getLockPath;
-    /**
-     * Acquire a soft lock for the given type + date.
-     * Uses `mkdirSync({ recursive: false })` for atomic creation on POSIX.
-     *
-     * @returns true if lock acquired, false if already held
-     */
-    acquireLock(type: string, date: string, workflowId: string): boolean;
-    /**
-     * Release a held lock.
-     */
-    releaseLock(type: string, date: string): void;
-    /**
-     * Check if a lock is currently held.
-     */
-    isLocked(type: string, date: string): boolean;
-    /**
-     * Read lock information if the lock exists.
-     */
-    getLockInfo(type: string, date: string): LockInfo | null;
-    /**
-     * Remove all locks older than the configured timeout.
-     *
-     * @returns Number of stale locks cleaned up
-     */
-    cleanupStaleLocks(): number;
-}
-/**
- * Workflow State Coordinator
- */
-export declare class WorkflowStateCoordinator {
-    private stateFilePath;
-    private state;
-    constructor(stateFilePath?: string);
-    /**
-     * Load state from disk
-     */
-    load(): Promise<void>;
-    /**
-     * Save state to disk using atomic write (write-to-tmp + rename).
-     */
-    save(): Promise<void>;
-    /**
-     * Clean up expired cache entries and old articles
-     */
-    cleanupExpiredEntries(): void;
-    /**
-     * Cache MCP query result with adaptive TTL.
-     *
-     * @param queryKey - Unique identifier for the query
-     * @param result - Query result to cache
-     * @param ttl - Time to live in seconds (default: adaptive based on plenary hours)
-     */
-    cacheMCPQuery(queryKey: string, result: unknown, ttl?: number): Promise<void>;
-    /**
-     * Get cached MCP query result
-     *
-     * @param queryKey - Unique identifier for the query
-     * @returns Cached result or null if expired/missing
-     */
-    getCachedMCPQuery(queryKey: string): unknown | null;
-    /**
-     * Add recent article to tracking
-     *
-     * @param article - Article metadata
-     */
-    addRecentArticle(article: RecentArticleInput): Promise<void>;
-    /**
-     * Check if article is duplicate based on similarity.
-     *
-     * Uses both weighted title/topic/source similarity (≥ 0.70 threshold)
-     * and Jaccard topic-only similarity (≥ 0.50 threshold) to catch
-     * same-topic articles with different titles.
-     *
-     * @param title - Article title
-     * @param topics - Article topics
-     * @param mcpQueries - MCP query keys used for this article
-     * @param significance - Optional political significance score (0-100).
-     *   When provided and ≥ 80, a same-topic article with lower significance
-     *   is NOT treated as a duplicate — the high-significance version overrides.
-     * @returns Duplicate check result with similarity score
-     */
-    checkDuplicateArticle(title: string, topics?: string[], mcpQueries?: string[], significance?: number): Promise<DuplicateCheckResult>;
-    /**
-     * Calculate similarity between two articles
-     *
-     * Uses weighted combination of:
-     * - Title similarity (50%)
-     * - Topic overlap (30%)
-     * - MCP query overlap (20%)
-     *
-     * @returns Similarity score 0.0-1.0
-     */
-    calculateSimilarity(title1: string, topics1: string[], mcpQueries1: string[], title2: string, topics2: string[], mcpQueries2: string[]): number;
-    /**
-     * Calculate string similarity using Jaccard similarity of word sets
-     *
-     * @param str1 - First string
-     * @param str2 - Second string
-     * @returns Similarity 0.0-1.0
-     */
-    stringSimilarity(str1: string, str2: string): number;
-    /**
-     * Calculate set overlap (Jaccard similarity)
-     *
-     * @param set1 - First set
-     * @param set2 - Second set
-     * @returns Overlap 0.0-1.0
-     */
-    setOverlap(set1: unknown[], set2: unknown[]): number;
-    /**
-     * Hash object for cache comparison
-     *
-     * @param obj - Object to hash
-     * @returns SHA-256 hash (first 16 hex chars)
-     */
-    hashObject(obj: unknown): string;
-    /**
-     * Record workflow execution
-     *
-     * @param workflowName - Name of workflow
-     * @param metadata - Execution metadata
-     */
-    recordWorkflowExecution(workflowName: string, metadata?: WorkflowExecutionMetadata): Promise<void>;
-    /**
-     * Register an active generation for cross-workflow visibility.
-     */
-    registerActiveGeneration(workflowId: string, type: string, date: string): Promise<void>;
-    /**
-     * Unregister an active generation when done.
-     */
-    unregisterActiveGeneration(workflowId: string, type: string, date: string): Promise<void>;
-    /**
-     * Get active generations for cross-workflow visibility.
-     */
-    getActiveGenerations(): ActiveGeneration[];
-    /**
-     * Get recent articles from last N hours
-     *
-     * @param hours - Hours to look back
-     * @returns Recent articles
-     */
-    getRecentArticles(hours?: number): RecentArticleEntry[];
-    /**
-     * Get workflow statistics
-     *
-     * @returns Statistics by workflow
-     */
-    getWorkflowStatistics(): WorkflowStatistics;
-}
-export { MCP_CACHE_TTL_SECONDS, MCP_CACHE_TTL_NON_PLENARY_SECONDS, RECENT_ARTICLE_TTL_SECONDS, SIMILARITY_THRESHOLD, TOPIC_JACCARD_THRESHOLD, LOCK_TIMEOUT_MS, ACTIVE_GENERATION_TTL_MS, };
-//# sourceMappingURL=workflow-state-coordinator.d.ts.map

package/dist/scripts/workflow-state-coordinator.d.ts.map

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