principles-disciple 1.127.0 → 1.129.0

package/dist/service/phase3-input-filter.js

@@ -0,0 +1,172 @@
+/**
+ * Phase 3 Input Filter
+ *
+ * CRITICAL: evaluatePhase3Inputs() does NOT read or use evolution_directive.json
+ * Directive is a compatibility-only display artifact, not a truth source.
+ *
+ * Phase 3 eligibility depends ONLY on:
+ * - Queue truth (valid evolution samples from queue)
+ *
+ * Any directive file is ignored for eligibility decisions.
+ *
+ * THREE-LANE CLASSIFICATION:
+ * - authoritative: Valid inputs that can be used for Phase 3 eligibility decisions
+ * - reference_only: Valid evidence that must NOT be used as positive eligibility input
+ *   (e.g., timeout-only outcomes - they indicate completion but not success)
+ * - rejected: Invalid, corrupt, or policy-prohibited input
+ */
+/**
+ * Legacy queue statuses that are rejected for Phase 3
+ */
+const LEGACY_QUEUE_STATUSES = ['resolved', 'blocked', 'failed', 'cancelled', 'paused'];
+function normalizeTaskId(value) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value.trim();
+    return normalized ? normalized : null;
+}
+function normalizeStatus(value) {
+    const normalized = typeof value === 'string' ? value.trim().toLowerCase() : '';
+    if (normalized === 'in_progress' || normalized === 'completed')
+        return normalized;
+    if (normalized === 'pending')
+        return 'pending';
+    return null;
+}
+/**
+ * Checks if a status is a legacy value that should be rejected
+ */
+function isLegacyStatus(value) {
+    const normalized = typeof value === 'string' ? value.trim().toLowerCase() : '';
+    return LEGACY_QUEUE_STATUSES.includes(normalized);
+}
+function normalizeTimestamp(value) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value.trim();
+    if (!normalized)
+        return null;
+    const timestamp = Date.parse(normalized);
+    return Number.isNaN(timestamp) ? null : normalized;
+}
+function dedupe(values) {
+    return [...new Set(values)];
+}
+/**
+ * Checks if a task has a timeout-only outcome (resolution indicates only timeout)
+ */
+function isTimeoutOnlyOutcome(item) {
+    const resolution = typeof item?.resolution === 'string' ? item.resolution.trim().toLowerCase() : '';
+    return resolution === 'auto_completed_timeout';
+}
+/**
+ * Evaluates Phase 3 readiness based on queue inputs.
+ *
+ * IMPORTANT: Does NOT use evolution_directive.json.
+ * Directive is compatibility-only display artifact, not a truth source.
+ * Queue is the only authoritative execution truth source for Phase 3.
+ *
+ * THREE-LANE CLASSIFICATION:
+ * - authoritative: Valid inputs for Phase 3 eligibility
+ * - reference_only: Valid evidence but not for eligibility (e.g., timeout outcomes)
+ * - rejected: Invalid, corrupt, or policy-prohibited input
+ *
+ * @param queue - Evolution queue items to validate
+ * @returns Phase 3 eligibility results
+ */
+export function evaluatePhase3Inputs(queue) {
+    const eligible = [];
+    const referenceOnly = [];
+    const rejected = [];
+    const taskIdCounts = new Map();
+    for (const item of queue) {
+        const taskId = normalizeTaskId(item?.id);
+        if (!taskId)
+            continue;
+        taskIdCounts.set(taskId, (taskIdCounts.get(taskId) ?? 0) + 1);
+    }
+    for (const item of queue) {
+        const taskId = normalizeTaskId(item?.id);
+        const status = normalizeStatus(item?.status);
+        const reasons = [];
+        const startedAt = normalizeTimestamp(item?.started_at);
+        const completedAt = normalizeTimestamp(item?.completed_at);
+        // Check for legacy statuses first (before other status validation)
+        if (isLegacyStatus(item?.status)) {
+            reasons.push('legacy_queue_status');
+        }
+        // Check for null status separately
+        if (item?.status === null) {
+            reasons.push('missing_status');
+        }
+        if (!taskId) {
+            reasons.push('missing_task_id');
+        }
+        else if ((taskIdCounts.get(taskId) ?? 0) > 1) {
+            reasons.push('reused_task_id');
+        }
+        // Only add invalid_status if it's not a legacy status and not null
+        if (!status && !isLegacyStatus(item?.status) && item?.status !== null) {
+            reasons.push('invalid_status');
+        }
+        if (typeof item?.started_at === 'string' && item.started_at.trim() && !startedAt) {
+            reasons.push('invalid_started_at');
+        }
+        if (typeof item?.completed_at === 'string' && item.completed_at.trim() && !completedAt) {
+            reasons.push('invalid_completed_at');
+        }
+        if (status === 'in_progress' && !startedAt) {
+            reasons.push('missing_started_at');
+        }
+        if (status === 'completed' && !completedAt) {
+            reasons.push('missing_completed_at');
+        }
+        // Handle rejected items first
+        if (reasons.length > 0) {
+            rejected.push({
+                taskId,
+                status: typeof item?.status === 'string' ? item.status : null,
+                reasons: dedupe(reasons),
+            });
+            continue;
+        }
+        if (!taskId || !status) {
+            continue;
+        }
+        // Check for timeout-only outcomes (REFERENCE_ONLY, not rejected)
+        // These are valid completions but shouldn't count as positive evidence
+        if (status === 'completed' && isTimeoutOnlyOutcome(item)) {
+            referenceOnly.push({
+                taskId,
+                status: 'completed',
+                classification: 'timeout_only',
+                reason: 'Task completed via timeout - valid execution but not positive capability evidence',
+            });
+            continue;
+        }
+        // Valid eligible sample
+        eligible.push({
+            taskId,
+            status,
+            startedAt,
+            completedAt,
+        });
+    }
+    // Queue is ready when:
+    // 1. Queue has items
+    // 2. No invalid/corrupt items (rejected is empty)
+    // 3. Either eligible OR referenceOnly has items (valid data exists)
+    // Note: referenceOnly (timeout outcomes) is valid data, just not positive evidence
+    const hasValidData = eligible.length > 0 || referenceOnly.length > 0;
+    const queueTruthReady = queue.length > 0 && rejected.length === 0 && hasValidData;
+    const phase3ShadowEligible = queueTruthReady && eligible.length > 0;
+    return {
+        queueTruthReady,
+        phase3ShadowEligible,
+        evolution: {
+            eligible,
+            referenceOnly,
+            rejected,
+        },
+    };
+}

package/dist/service/queue-io.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Queue I/O + Enqueue — extracted from evolution-worker.ts
+ *
+ * Full persistence layer encapsulating queue file locking, atomic writes,
+ * queue format, and enqueue orchestration. Depends on file-lock.ts, io.ts,
+ * queue-migration.ts, and pain.ts.
+ * Zero imports from evolution-worker.ts.
+ */
+import type { EvolutionQueueItem } from '../core/evolution-types.js';
+import type { PluginLogger } from '../openclaw-sdk.js';
+export declare const EVOLUTION_QUEUE_LOCK_SUFFIX = ".lock";
+export declare const LOCK_MAX_RETRIES = 50;
+export declare const LOCK_RETRY_DELAY_MS = 50;
+export declare const LOCK_STALE_MS = 30000;
+export declare function requireQueueLock(resourcePath: string, logger: PluginLogger | {
+    warn?: (message: string) => void;
+    info?: (message: string) => void;
+} | undefined, scope: string, lockSuffix?: string): Promise<() => void>;
+export declare function createEvolutionTaskId(source: string, score: number, preview: string, reason: string, now: number): string;
+export declare function hasPendingTask(queue: EvolutionQueueItem[], taskKind: string): boolean;
+export declare function acquireQueueLock(resourcePath: string, logger: PluginLogger | {
+    warn?: (message: string) => void;
+    info?: (message: string) => void;
+} | undefined, lockSuffix?: string): Promise<() => void>;
+export declare function withQueueLock<T>(resourcePath: string, logger: PluginLogger | {
+    warn?: (message: string) => void;
+    info?: (message: string) => void;
+} | undefined, scope: string, fn: () => Promise<T>): Promise<T>;
+export declare function loadEvolutionQueue(queuePath: string): EvolutionQueueItem[];
+export declare function saveEvolutionQueue(queuePath: string, queue: EvolutionQueueItem[]): void;

package/dist/service/queue-io.js

@@ -0,0 +1,79 @@
+/**
+ * Queue I/O + Enqueue — extracted from evolution-worker.ts
+ *
+ * Full persistence layer encapsulating queue file locking, atomic writes,
+ * queue format, and enqueue orchestration. Depends on file-lock.ts, io.ts,
+ * queue-migration.ts, and pain.ts.
+ * Zero imports from evolution-worker.ts.
+ */
+import * as fs from 'fs';
+import { createHash } from 'crypto';
+import { acquireLockAsync, releaseLock as releaseImportedLock } from '../utils/file-lock.js';
+import { atomicWriteFileSync } from '../utils/io.js';
+import { LockUnavailableError } from '../config/errors.js';
+import { migrateQueueToV2 } from './queue-migration.js';
+export const EVOLUTION_QUEUE_LOCK_SUFFIX = '.lock';
+export const LOCK_MAX_RETRIES = 50;
+export const LOCK_RETRY_DELAY_MS = 50;
+export const LOCK_STALE_MS = 30_000;
+export async function requireQueueLock(resourcePath, logger, scope, lockSuffix = EVOLUTION_QUEUE_LOCK_SUFFIX) {
+    try {
+        return await acquireQueueLock(resourcePath, logger, lockSuffix);
+    }
+    catch (err) {
+        throw new LockUnavailableError(resourcePath, scope, { cause: err });
+    }
+}
+export function createEvolutionTaskId(source, score, preview, reason, now) {
+    return createHash('md5')
+        .update(`${source}:${score}:${preview}:${reason}:${now}`)
+        .digest('hex')
+        .substring(0, 8);
+}
+export function hasPendingTask(queue, taskKind) {
+    return queue.some((t) => t.taskKind === taskKind && (t.status === 'pending' || t.status === 'in_progress'));
+}
+export async function acquireQueueLock(resourcePath, logger, lockSuffix = EVOLUTION_QUEUE_LOCK_SUFFIX) {
+    try {
+        const ctx = await acquireLockAsync(resourcePath, {
+            lockSuffix,
+            maxRetries: LOCK_MAX_RETRIES,
+            baseRetryDelayMs: LOCK_RETRY_DELAY_MS,
+            lockStaleMs: LOCK_STALE_MS,
+        });
+        return () => releaseImportedLock(ctx);
+    }
+    catch (error) {
+        const warn = logger?.warn;
+        warn?.(`[PD:EvolutionWorker] Failed to acquire lock for ${resourcePath}: ${String(error)}`);
+        throw error;
+    }
+}
+export async function withQueueLock(resourcePath, logger, scope, fn) {
+    const releaseLock = await acquireQueueLock(resourcePath, logger, EVOLUTION_QUEUE_LOCK_SUFFIX);
+    try {
+        return await fn();
+    }
+    finally {
+        releaseLock();
+    }
+}
+export function loadEvolutionQueue(queuePath) {
+    let rawQueue = [];
+    try {
+        rawQueue = JSON.parse(fs.readFileSync(queuePath, 'utf8'));
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            rawQueue = [];
+        }
+        else {
+            console.warn(`[queue-io] Failed to load evolution queue (recovering with empty): ${String(err)}`);
+            rawQueue = [];
+        }
+    }
+    return migrateQueueToV2(rawQueue);
+}
+export function saveEvolutionQueue(queuePath, queue) {
+    atomicWriteFileSync(queuePath, JSON.stringify(queue, null, 2));
+}

package/{src/service/queue-migration.ts → dist/service/queue-migration.d.ts}

@@ -4,10 +4,7 @@
  * Pure data transformation functions for migrating legacy queue items
  * to the V2 schema. Zero I/O, zero imports from evolution-worker.ts.
  */
-
 import type { TaskKind, TaskPriority } from '../core/trajectory-types.js';
-
-// V2 types (not exported from evolution-types.ts — defined here for self-containment)
 export type QueueStatus = 'pending' | 'in_progress' | 'completed' | 'failed';
 export type TaskResolution = 'success' | 'failure' | 'skipped';
 export interface EvolutionQueueItem {
@@ -34,7 +31,6 @@ export interface EvolutionQueueItem {
     lastError?: string;
     resultRef?: string;
 }
-
 /**
  * Legacy queue item shape (pre-V2) for migration compatibility.
  * These items lack taskKind, priority, retryCount, maxRetries, lastError fields.
@@ -63,60 +59,25 @@ export interface LegacyEvolutionQueueItem {
     lastError?: string;
     resultRef?: string;
 }
-
 /**
  * Default values for new V2 fields when migrating legacy items.
  */
-const DEFAULT_TASK_KIND: TaskKind = 'pain_diagnosis';
-const DEFAULT_PRIORITY: TaskPriority = 'medium';
-const DEFAULT_MAX_RETRIES = 3;
-
+declare const DEFAULT_TASK_KIND: TaskKind;
+declare const DEFAULT_PRIORITY: TaskPriority;
+declare const DEFAULT_MAX_RETRIES = 3;
 export { DEFAULT_TASK_KIND, DEFAULT_PRIORITY, DEFAULT_MAX_RETRIES };
-
 export type RawQueueItem = Record<string, unknown>;
-
 /**
  * Migrate a legacy queue item to V2 schema.
  * Old items without taskKind are assumed to be pain_diagnosis for backward compatibility.
  */
-export function migrateToV2(item: LegacyEvolutionQueueItem): EvolutionQueueItem {
-    return {
-        id: item.id,
-        taskKind: (item.taskKind as TaskKind) || DEFAULT_TASK_KIND,
-        priority: (item.priority as TaskPriority) || DEFAULT_PRIORITY,
-        source: item.source,
-        traceId: item.traceId,
-        task: item.task,
-        score: item.score,
-        reason: item.reason,
-        timestamp: item.timestamp,
-        enqueued_at: item.enqueued_at,
-        started_at: item.started_at,
-        completed_at: item.completed_at,
-        assigned_session_key: item.assigned_session_key,
-        trigger_text_preview: item.trigger_text_preview,
-        status: (item.status as QueueStatus) || 'pending',
-        resolution: item.resolution as TaskResolution | undefined,
-        session_id: item.session_id,
-        agent_id: item.agent_id,
-        retryCount: item.retryCount || 0,
-        maxRetries: item.maxRetries || DEFAULT_MAX_RETRIES,
-        lastError: item.lastError,
-        resultRef: item.resultRef,
-    };
-}
-
+export declare function migrateToV2(item: LegacyEvolutionQueueItem): EvolutionQueueItem;
 /**
  * Check if an item is a legacy (pre-V2) queue item.
  */
-export function isLegacyQueueItem(item: RawQueueItem): boolean {
-    return item && typeof item === 'object' && !('taskKind' in item);
-}
-
+export declare function isLegacyQueueItem(item: RawQueueItem): boolean;
 /**
  * Migrate entire queue to V2 schema if needed.
  * Returns a new array with all items migrated to V2 format.
  */
-export function migrateQueueToV2(queue: RawQueueItem[]): EvolutionQueueItem[] {
-    return queue.map(item => isLegacyQueueItem(item) ? migrateToV2(item as unknown as LegacyEvolutionQueueItem) : item as unknown as EvolutionQueueItem);
-}
+export declare function migrateQueueToV2(queue: RawQueueItem[]): EvolutionQueueItem[];

package/dist/service/queue-migration.js

@@ -0,0 +1,56 @@
+/**
+ * Queue Migration — extracted from evolution-worker.ts (lines 297-379)
+ *
+ * Pure data transformation functions for migrating legacy queue items
+ * to the V2 schema. Zero I/O, zero imports from evolution-worker.ts.
+ */
+/**
+ * Default values for new V2 fields when migrating legacy items.
+ */
+const DEFAULT_TASK_KIND = 'pain_diagnosis';
+const DEFAULT_PRIORITY = 'medium';
+const DEFAULT_MAX_RETRIES = 3;
+export { DEFAULT_TASK_KIND, DEFAULT_PRIORITY, DEFAULT_MAX_RETRIES };
+/**
+ * Migrate a legacy queue item to V2 schema.
+ * Old items without taskKind are assumed to be pain_diagnosis for backward compatibility.
+ */
+export function migrateToV2(item) {
+    return {
+        id: item.id,
+        taskKind: item.taskKind || DEFAULT_TASK_KIND,
+        priority: item.priority || DEFAULT_PRIORITY,
+        source: item.source,
+        traceId: item.traceId,
+        task: item.task,
+        score: item.score,
+        reason: item.reason,
+        timestamp: item.timestamp,
+        enqueued_at: item.enqueued_at,
+        started_at: item.started_at,
+        completed_at: item.completed_at,
+        assigned_session_key: item.assigned_session_key,
+        trigger_text_preview: item.trigger_text_preview,
+        status: item.status || 'pending',
+        resolution: item.resolution,
+        session_id: item.session_id,
+        agent_id: item.agent_id,
+        retryCount: item.retryCount || 0,
+        maxRetries: item.maxRetries || DEFAULT_MAX_RETRIES,
+        lastError: item.lastError,
+        resultRef: item.resultRef,
+    };
+}
+/**
+ * Check if an item is a legacy (pre-V2) queue item.
+ */
+export function isLegacyQueueItem(item) {
+    return item && typeof item === 'object' && !('taskKind' in item);
+}
+/**
+ * Migrate entire queue to V2 schema if needed.
+ * Returns a new array with all items migrated to V2 format.
+ */
+export function migrateQueueToV2(queue) {
+    return queue.map(item => isLegacyQueueItem(item) ? migrateToV2(item) : item);
+}

package/dist/service/runtime-summary-service.d.ts

@@ -0,0 +1,158 @@
+import type { WorkflowStage } from '../core/workflow-funnel-loader.js';
+import type { RuntimeTruth, AnalyticsTruth } from '../types/runtime-summary.js';
+import type { GfiWorkspaceSnapshot } from '@principles/core/runtime-v2';
+export type RuntimeDataQuality = 'authoritative' | 'partial';
+export type RuntimeRewardPolicy = 'frozen_all_positive' | 'frozen_atomic_positive_keep_plan_ready';
+interface RuntimeSummarySource {
+    source: string;
+    score?: number;
+    ts?: string;
+    confidence?: number;
+    origin?: string;
+}
+interface RuntimePainSignal {
+    source: string;
+    ts: string | null;
+    reason: string | null;
+}
+export interface RuntimeSummary {
+    /**
+     * Runtime truth represents the current state of the system.
+     * Used for control decisions, Phase 3 eligibility, and real-time operations.
+     */
+    runtime: RuntimeTruth;
+    /**
+     * Analytics truth represents historical data and aggregated metrics.
+     * Used for insights, trends, and supporting evidence (where explicitly allowed).
+     * NOT used for control decisions or Phase 3 eligibility.
+     */
+    analytics: AnalyticsTruth;
+    gfi: {
+        current: number | null;
+        peak: number | null;
+        sources: RuntimeSummarySource[];
+        dataQuality: RuntimeDataQuality;
+        workspaceSnapshot?: GfiWorkspaceSnapshot;
+    };
+    evolution: {
+        queue: {
+            pending: number;
+            inProgress: number;
+            completed: number;
+        };
+        directive: {
+            exists: boolean;
+            active: boolean | null;
+            ageSeconds: number | null;
+            taskPreview: string | null;
+        };
+        dataQuality: RuntimeDataQuality;
+    };
+    runtimeDiagnosis: {
+        /** Tasks pending in diagnostician_tasks.json (not yet processed by heartbeat) */
+        pendingTasks: number;
+        /** Total diagnosis tasks written by evolution worker (today from event log) */
+        tasksWrittenToday: number;
+        /** Total diagnostician reports written (today from event log) */
+        reportsWrittenToday: number;
+        /** Total diagnostician reports that were missing JSON (category=missing_json) */
+        reportsMissingJsonToday: number;
+        /** Total diagnostician reports with incomplete fields (category=incomplete_fields) */
+        reportsIncompleteFieldsToday: number;
+        /** Total principle candidates created from heartbeat chain (today from event log) */
+        candidatesCreatedToday: number;
+        /** Heartbeats that injected diagnostician tasks (today from event log) */
+        heartbeatsInjectedToday: number;
+    };
+    phase3: {
+        queueTruthReady: boolean;
+        phase3ShadowEligible: boolean;
+        evolutionEligible: number;
+        evolutionReferenceOnly: number;
+        evolutionReferenceOnlyReasons: string[];
+        evolutionRejected: number;
+        evolutionRejectedReasons: string[];
+        legacyDirectiveFilePresent: boolean;
+        directiveStatus: 'compatibility-only' | 'missing' | 'present';
+        directiveIgnoredReason: string;
+        /**
+         * Source of Phase 3 eligibility calculation.
+         * Should always be 'runtime_truth' - analytics not used for control decisions.
+         */
+        eligibilitySource: 'runtime_truth';
+    };
+    pain: {
+        activeFlag: boolean;
+        activeFlagSource: string | null;
+        candidates: number | null;
+        lastSignal: RuntimePainSignal | null;
+    };
+    gate: {
+        recentBlocks: number | null;
+        recentBypasses: number | null;
+        dataQuality: RuntimeDataQuality;
+    };
+    /** YAML-driven funnel counts — only present when funnels param is provided (YAML-SSOT-01) */
+    workflowFunnels?: WorkflowFunnelOutput[];
+    metadata: {
+        generatedAt: string;
+        workspaceDir: string;
+        sessionId: string | null;
+        selectedSessionReason: 'explicit' | 'latest_active' | 'none';
+        /** 'degraded' when YAML load errors or unresolved statsField paths exist; 'ok' otherwise */
+        status: 'ok' | 'degraded';
+        warnings: string[];
+    };
+}
+export interface WorkflowFunnelStageOutput {
+    key: string;
+    label: string;
+    statsField: string;
+    count: number;
+}
+export interface WorkflowFunnelOutput {
+    funnelKey: string;
+    funnelLabel: string;
+    stages: WorkflowFunnelStageOutput[];
+}
+export declare class RuntimeSummaryService {
+    static getSummary(workspaceDir: string, options?: {
+        sessionId?: string | null;
+        loaderWarnings?: string[];
+        funnels?: Map<string, WorkflowStage[]>;
+    }): RuntimeSummary;
+    private static readSessions;
+    private static selectSession;
+    private static mergeSessionSnapshots;
+    private static buildQueueStats;
+    /**
+     * Builds directive summary for compatibility display only.
+     * NOT a truth source for Phase 3 eligibility or decisions.
+     * Queue is the only authoritative execution truth source.
+     */
+    private static buildDirectiveSummary;
+    private static readEvents;
+    private static buildGfiSources;
+    private static findLastPainSignal;
+    private static buildGateStats;
+    private static resolveSessionSortTime;
+    private static mergeEvents;
+    private static getEventDedupKey;
+    private static resolveEvolutionDataQuality;
+    private static selectInProgressTask;
+    private static getQueuePriority;
+    private static isResolvableEvolutionTask;
+    private static resolveDirectiveTimestamp;
+    private static buildDirectiveTaskPreview;
+    private static warnOnLegacyDirectiveMismatch;
+    private static readJsonFile;
+    private static asFiniteNumber;
+    /**
+     * Read trajectory analytics data from trajectory database.
+     *
+     * Returns: Analytics data (historical metrics) aggregated from trajectory database.
+     * Not: Runtime truth or real-time queue state.
+     */
+    private static readTrajectoryStats;
+}
+export {};