principles-disciple 1.127.0 → 1.129.0

package/dist/service/internalization-auto-consumer-service.d.ts

@@ -0,0 +1,8 @@
+import type { OpenClawPluginServiceContext, PluginLogger } from '../openclaw-sdk.js';
+export interface InternalizationAutoConsumerServiceShape {
+    id: string;
+    start: (ctx: OpenClawPluginServiceContext) => void;
+    stop?: (ctx: OpenClawPluginServiceContext) => void;
+}
+export declare function runConsumerCycle(workspaceDir: string, logger: PluginLogger): Promise<void>;
+export declare const InternalizationAutoConsumerService: InternalizationAutoConsumerServiceShape;

package/dist/service/internalization-auto-consumer-service.js

@@ -0,0 +1,322 @@
+import { createRuntimeStateHandle, InternalizationOrchestrator, DreamerRunner, DefaultDreamerValidator, PiAiRuntimeAdapter, L2AgentLoopAdapter, buildL2PrincipleReaderFromLedger, loadLedger, OpenClawCliRuntimeAdapter, storeEmitter, resolveRuntimeConfigFromPdConfig, isRuntimeConfigError, computeConsumerDecision, InternalizationQueueReadModel, MVP_CORE_TASK_KINDS, } from '@principles/core/runtime-v2';
+import { loadPdConfigForPlugin, loadFeatureFlagFromConfig } from '../core/pd-config-loader.js';
+import { SystemLogger } from '../core/system-logger.js';
+const INTERNALIZATION_AUTO_CONSUMER_INTERVAL_MS = 120_000;
+const INTERNALIZATION_AUTO_CONSUMER_INITIAL_DELAY_MS = 30_000;
+const INTERNALIZATION_AUTO_CONSUMER_FLAG_ID = 'internalization_auto_consumer';
+const workspaceStates = new Map();
+function getWorkspaceState(workspaceDir) {
+    let state = workspaceStates.get(workspaceDir);
+    if (!state) {
+        state = { stopped: false, timeoutId: null };
+        workspaceStates.set(workspaceDir, state);
+    }
+    return state;
+}
+function formatRunOnceCommand(workspaceDir) {
+    return `pd runtime internalization run-once --workspace "${workspaceDir}" --runner dreamer --runtime config --json`;
+}
+function getNextActionForError(category) {
+    if (category === 'lease_conflict') {
+        return 'Retry later or check for concurrent worker processes.';
+    }
+    if (category === 'timeout') {
+        return 'Check model provider service status/latency, or increase timeout settings in workflows.yaml.';
+    }
+    if (category === 'cancelled') {
+        return 'Re-enqueue or restart the task if it was cancelled by mistake.';
+    }
+    if (category === 'output_invalid') {
+        return 'Verify if model outputs conform to expected schema and adjust prompt or validation templates if needed.';
+    }
+    if (category === 'input_invalid') {
+        return 'Check predecessor task outputs and database integrity for malformed input references.';
+    }
+    if (category === 'max_attempts_exceeded') {
+        return 'Investigate persistent failures, correct the root issue, and clear last_error or reset attempt count.';
+    }
+    return 'Run: pd runtime internalization run-once --runner dreamer --runtime config --json to isolate the failure.';
+}
+export async function runConsumerCycle(workspaceDir, logger) {
+    const flag = loadFeatureFlagFromConfig(workspaceDir, INTERNALIZATION_AUTO_CONSUMER_FLAG_ID, {
+        info: (msg) => logger.info(msg),
+        warn: (msg) => logger.warn(msg),
+    });
+    if (!flag.enabled) {
+        const disabledInfo = JSON.stringify({
+            reason: 'internalization_auto_consumer_disabled',
+            nextAction: formatRunOnceCommand(workspaceDir),
+            flagSource: flag.source,
+        });
+        SystemLogger.log(workspaceDir, 'INTERNALIZATION_CONSUMER_SKIP', disabledInfo);
+        logger.info(`[PD:AutoConsumer] Cycle skipped: auto-consumer disabled. Source: ${flag.source}`);
+        return;
+    }
+    const configResult = loadPdConfigForPlugin(workspaceDir);
+    if (!configResult.ok) {
+        const malformedInfo = JSON.stringify({
+            reason: 'config_malformed',
+            nextAction: configResult.errors[0]?.nextAction ?? 'Fix .pd/config.yaml and retry',
+            errors: configResult.errors.map((e) => e.reason),
+        });
+        SystemLogger.log(workspaceDir, 'INTERNALIZATION_CONSUMER_SKIP', malformedInfo);
+        logger.warn(`[PD:AutoConsumer] Config malformed, skipping cycle.`);
+        return;
+    }
+    const runtimeConfigResult = resolveRuntimeConfigFromPdConfig(configResult.effective, (name) => process.env[name]);
+    if (isRuntimeConfigError(runtimeConfigResult)) {
+        const rtInfo = JSON.stringify({
+            reason: 'runtime_config_error',
+            message: runtimeConfigResult.message,
+            nextAction: runtimeConfigResult.nextAction,
+        });
+        SystemLogger.log(workspaceDir, 'INTERNALIZATION_CONSUMER_SKIP', rtInfo);
+        logger.warn(`[PD:AutoConsumer] Runtime config error: ${runtimeConfigResult.message}`);
+        return;
+    }
+    let handle = null;
+    try {
+        handle = await createRuntimeStateHandle({ workspaceDir, readonly: false });
+        const { stateManager } = handle;
+        const readModel = new InternalizationQueueReadModel(stateManager);
+        readModel.setPolicy({
+            enabledChannels: new Set(['prompt', 'code_tool_hook', 'defer_archive']),
+            actionableTaskKinds: new Set(MVP_CORE_TASK_KINDS),
+        });
+        const snapshot = await readModel.getSnapshot();
+        if (snapshot.readyTasks.length > 5) {
+            logger.warn(`[PD:AutoConsumer] Backlog detected: ${snapshot.readyTasks.length} tasks ready. Processing only one task.`);
+        }
+        const decision = computeConsumerDecision({
+            autoConsumerEnabled: true,
+            readyTaskCount: snapshot.readyTasks.length,
+        });
+        if (!decision.shouldConsume) {
+            SystemLogger.log(workspaceDir, 'INTERNALIZATION_CONSUMER_SKIP', JSON.stringify({
+                reason: decision.reason,
+                readyTaskCount: snapshot.readyTasks.length,
+            }));
+            return;
+        }
+        const runtimeKind = runtimeConfigResult.runtimeKind;
+        const orchestrator = new InternalizationOrchestrator({ stateManager }, { owner: 'auto-consumer', runtimeKind, dryRun: true });
+        const wakeResult = await orchestrator.wakeOnce('dreamer');
+        if (wakeResult.decision !== 'would_lease') {
+            const skipPayload = {
+                decision: wakeResult.decision,
+            };
+            if (wakeResult.decision === 'no_ready_tasks') {
+                skipPayload.reason = wakeResult.reason;
+            }
+            SystemLogger.log(workspaceDir, 'INTERNALIZATION_CONSUMER_SKIP', JSON.stringify(skipPayload));
+            logger.info(`[PD:AutoConsumer] No task to consume: ${wakeResult.decision}`);
+            return;
+        }
+        let adapter;
+        if (runtimeKind === 'pi-ai') {
+            // PRI-419: when l2_dreamer flag is on, route through the L2 multi-turn agent loop.
+            const l2Flag = loadFeatureFlagFromConfig(workspaceDir, 'l2_dreamer');
+            if (l2Flag.enabled) {
+                const stateDir = `${workspaceDir}/.state`;
+                const principleReader = buildL2PrincipleReaderFromLedger(loadLedger(stateDir), {
+                    logger: { warn: (msg) => logger.warn(msg) },
+                });
+                adapter = new L2AgentLoopAdapter({
+                    provider: runtimeConfigResult.provider ?? 'openai',
+                    model: runtimeConfigResult.model ?? 'gpt-4o',
+                    apiKeyEnv: runtimeConfigResult.apiKeyEnv ?? 'OPENAI_API_KEY',
+                    baseUrl: runtimeConfigResult.baseUrl,
+                    workspace: workspaceDir,
+                    totalBudgetMs: runtimeConfigResult.timeoutMs,
+                }, {
+                    artifactReader: {
+                        // Explicit adapter: PIArtifactRecord → PdL2ArtifactReader. The store returns
+                        // PIArtifactRecord (with PIArtifactKind enum); map to the ArtifactSummary shape.
+                        getArtifactById: async (id) => {
+                            const r = await stateManager.piArtifactStore.getArtifactById(id);
+                            return r ? { artifactId: r.artifactId, artifactKind: String(r.artifactKind), sourceTaskId: r.sourceTaskId, contentJson: r.contentJson, createdAt: r.createdAt } : null;
+                        },
+                        listBySourceTaskId: async (taskId) => {
+                            const records = await stateManager.piArtifactStore.listBySourceTaskId(taskId);
+                            return records.map(r => ({ artifactId: r.artifactId, artifactKind: String(r.artifactKind), sourceTaskId: r.sourceTaskId, contentJson: r.contentJson, createdAt: r.createdAt }));
+                        },
+                    },
+                    principleReader,
+                });
+            }
+            else {
+                adapter = new PiAiRuntimeAdapter({
+                    provider: runtimeConfigResult.provider ?? 'openai',
+                    model: runtimeConfigResult.model ?? 'gpt-4o',
+                    apiKeyEnv: runtimeConfigResult.apiKeyEnv ?? 'OPENAI_API_KEY',
+                    maxRetries: runtimeConfigResult.maxRetries,
+                    timeoutMs: runtimeConfigResult.timeoutMs,
+                    baseUrl: runtimeConfigResult.baseUrl,
+                    workspace: workspaceDir,
+                });
+            }
+        }
+        else if (runtimeKind === 'openclaw-cli') {
+            adapter = new OpenClawCliRuntimeAdapter({
+                runtimeMode: runtimeConfigResult.openclawMode ?? 'default',
+                workspaceDir: workspaceDir,
+            });
+        }
+        else {
+            throw new Error(`Unsupported runtime kind resolved for auto-consumer: ${runtimeKind}`);
+        }
+        const validator = new DefaultDreamerValidator();
+        const runner = new DreamerRunner({
+            stateManager,
+            runtimeAdapter: adapter,
+            eventEmitter: storeEmitter,
+            artifactStore: stateManager.piArtifactStore,
+            validator,
+        }, {
+            owner: 'auto-consumer',
+            runtimeKind,
+        });
+        const taskId = wakeResult.taskId;
+        logger.info(`[PD:AutoConsumer] Running dreamer task: ${taskId}`);
+        SystemLogger.log(workspaceDir, 'INTERNALIZATION_CONSUMER_RUN', JSON.stringify({
+            taskId,
+            taskKind: 'dreamer',
+        }));
+        let runResult;
+        try {
+            runResult = await runner.run(taskId);
+        }
+        catch (runErr) {
+            logger.error(`[PD:AutoConsumer] Runner crashed for task ${taskId}: ${String(runErr)}`);
+            try {
+                const task = await stateManager.getTask(taskId);
+                const failureReason = `Unhandled runner exception: ${runErr instanceof Error ? runErr.message : String(runErr)}`;
+                if (task && stateManager.getRetryPolicy().shouldRetry(task)) {
+                    await stateManager.markTaskRetryWait(taskId, 'execution_failed', failureReason);
+                    logger.info(`[PD:AutoConsumer] Marked task ${taskId} as retry_wait.`);
+                }
+                else {
+                    await stateManager.markTaskFailed(taskId, 'execution_failed', failureReason);
+                    logger.info(`[PD:AutoConsumer] Marked task ${taskId} as failed.`);
+                }
+            }
+            catch (dbErr) {
+                logger.error(`[PD:AutoConsumer] Failed to update state for crashed task ${taskId}: ${String(dbErr)}`);
+            }
+            throw runErr;
+        }
+        if (runResult.status === 'succeeded') {
+            const commitResult = await orchestrator.commitNextTaskProposal(taskId);
+            SystemLogger.log(workspaceDir, 'INTERNALIZATION_CONSUMER_SUCCESS', JSON.stringify({
+                taskId,
+                status: runResult.status,
+                successorDecision: commitResult.decision,
+            }));
+            logger.info(`[PD:AutoConsumer] Task ${taskId} succeeded. Successor: ${commitResult.decision}`);
+        }
+        else {
+            const errorCategory = runResult.errorCategory;
+            const failureReason = runResult.failureReason;
+            const nextAction = getNextActionForError(errorCategory);
+            SystemLogger.log(workspaceDir, 'INTERNALIZATION_CONSUMER_TASK_FAILED', JSON.stringify({
+                taskId,
+                status: runResult.status,
+                errorCategory,
+                failureReason,
+                nextAction,
+            }));
+            logger.warn(`[PD:AutoConsumer] Task ${taskId} status: ${runResult.status}. Category: ${errorCategory}. Reason: ${failureReason}. Next Action: ${nextAction}`);
+        }
+    }
+    catch (err) {
+        SystemLogger.log(workspaceDir, 'INTERNALIZATION_CONSUMER_ERROR', String(err));
+        logger.error(`[PD:AutoConsumer] Cycle error: ${String(err)}`);
+    }
+    finally {
+        if (handle) {
+            await handle.close().catch(() => { });
+        }
+    }
+}
+export const InternalizationAutoConsumerService = {
+    id: 'principles-internalization-auto-consumer',
+    start(ctx) {
+        const maybeWorkspaceDir = ctx?.workspaceDir;
+        const logger = ctx?.logger || console;
+        if (!maybeWorkspaceDir) {
+            logger.warn('[PD:AutoConsumer] No workspace directory, not starting.');
+            return;
+        }
+        const workspaceDir = maybeWorkspaceDir;
+        const state = getWorkspaceState(workspaceDir);
+        if (!state.stopped && state.timeoutId !== null) {
+            logger.info(`[PD:AutoConsumer] Already started for workspace: ${workspaceDir}`);
+            return;
+        }
+        const flag = loadFeatureFlagFromConfig(workspaceDir, INTERNALIZATION_AUTO_CONSUMER_FLAG_ID, {
+            info: (msg) => logger.info(msg),
+            warn: (msg) => logger.warn(msg),
+        });
+        if (!flag.enabled) {
+            const disabledInfo = JSON.stringify({
+                reason: 'internalization_auto_consumer_disabled',
+                nextAction: formatRunOnceCommand(workspaceDir),
+                flagSource: flag.source,
+            });
+            SystemLogger.log(workspaceDir, 'INTERNALIZATION_CONSUMER_DISABLED', disabledInfo);
+            logger.info(`[PD:AutoConsumer] NOT started for workspace: ${workspaceDir}. Disabled (source: ${flag.source}).`);
+            return;
+        }
+        state.stopped = false;
+        const interval = INTERNALIZATION_AUTO_CONSUMER_INTERVAL_MS;
+        function scheduleNext() {
+            if (state.stopped)
+                return;
+            state.timeoutId = setTimeout(runCycle, interval);
+            state.timeoutId?.unref();
+        }
+        async function runCycle() {
+            if (state.stopped)
+                return;
+            await runConsumerCycle(workspaceDir, logger);
+            scheduleNext();
+        }
+        state.timeoutId = setTimeout(() => {
+            void runCycle().catch((err) => {
+                logger.error(`[PD:AutoConsumer] Startup cycle failed: ${String(err)}`);
+                if (state.stopped)
+                    return;
+                state.timeoutId = setTimeout(runCycle, interval);
+                state.timeoutId?.unref();
+            });
+        }, INTERNALIZATION_AUTO_CONSUMER_INITIAL_DELAY_MS);
+        state.timeoutId?.unref();
+        SystemLogger.log(workspaceDir, 'INTERNALIZATION_CONSUMER_STARTED', JSON.stringify({
+            intervalMs: interval,
+            initialDelayMs: INTERNALIZATION_AUTO_CONSUMER_INITIAL_DELAY_MS,
+        }));
+        logger.info(`[PD:AutoConsumer] Started for workspace: ${workspaceDir} (interval: ${interval}ms, initial delay: ${INTERNALIZATION_AUTO_CONSUMER_INITIAL_DELAY_MS}ms)`);
+    },
+    stop(ctx) {
+        const workspaceDir = ctx?.workspaceDir;
+        if (workspaceDir) {
+            const state = workspaceStates.get(workspaceDir);
+            if (state) {
+                state.stopped = true;
+                if (state.timeoutId)
+                    clearTimeout(state.timeoutId);
+                state.timeoutId = null;
+            }
+            workspaceStates.delete(workspaceDir);
+        }
+        else {
+            for (const [, state] of workspaceStates) {
+                state.stopped = true;
+                if (state.timeoutId)
+                    clearTimeout(state.timeoutId);
+                state.timeoutId = null;
+            }
+            workspaceStates.clear();
+        }
+    },
+};

package/dist/service/keyword-optimization-service.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Keyword Optimization Service
+ *
+ * Applies LLM optimization results (ADD/UPDATE/REMOVE mutations) to the
+ * correction keyword store. Called by evolution-worker.ts after the
+ * keyword_optimization workflow completes.
+ */
+import type { CorrectionObserverOutputV1 as CorrectionObserverResult } from '@principles/core/runtime-v2';
+import type { PluginLogger } from '../openclaw-sdk.js';
+/**
+ * Applies CorrectionObserverResult mutations to the keyword store.
+ * - ADD: calls learner.add() with new keyword
+ * - UPDATE: updates weight on existing keyword
+ * - REMOVE: removes keyword from store
+ */
+export declare class KeywordOptimizationService {
+    private readonly stateDir;
+    private readonly workspaceDir;
+    private readonly logger;
+    constructor(stateDir: string, workspaceDir: string, logger: PluginLogger);
+    applyResult(result: CorrectionObserverResult): void;
+    /**
+     * Builds trajectory history for payload:
+     * - Calls TrajectoryDatabase.listUserTurnsForSession() for recent sessions
+     * - Filters to turns where correctionDetected=true
+     * - Returns last 50 correction events
+     */
+    buildTrajectoryHistory(sessionIds: string[]): Promise<TrajectoryHistoryEntry[]>;
+    private static _instances;
+    static get(stateDir: string, workspaceDir: string, logger: PluginLogger): KeywordOptimizationService;
+    static reset(): void;
+}
+/**
+ * Internal type mirroring the trajectoryHistory field in CorrectionObserverPayload.
+ * Exported here so buildTrajectoryHistory can reference it without a circular import.
+ */
+export type TrajectoryHistoryEntry = {
+    sessionId: string;
+    timestamp: string;
+    term: string;
+    userMessage: string;
+};
+/** Re-export CorrectionObserverPayload for convenience */
+export type { CorrectionObserverPayload } from '@principles/core/runtime-v2';

package/dist/service/keyword-optimization-service.js

@@ -0,0 +1,137 @@
+/**
+ * Keyword Optimization Service
+ *
+ * Applies LLM optimization results (ADD/UPDATE/REMOVE mutations) to the
+ * correction keyword store. Called by evolution-worker.ts after the
+ * keyword_optimization workflow completes.
+ */
+import { CorrectionCueLearner } from '../core/correction-cue-learner.js';
+import { TrajectoryRegistry } from '../core/trajectory.js';
+/**
+ * Applies CorrectionObserverResult mutations to the keyword store.
+ * - ADD: calls learner.add() with new keyword
+ * - UPDATE: updates weight on existing keyword
+ * - REMOVE: removes keyword from store
+ */
+export class KeywordOptimizationService {
+    stateDir;
+    workspaceDir;
+    logger;
+    constructor(stateDir, workspaceDir, logger) {
+        this.stateDir = stateDir;
+        this.workspaceDir = workspaceDir;
+        this.logger = logger;
+    }
+    applyResult(result) {
+        const learner = CorrectionCueLearner.get(this.stateDir);
+        const updates = result.updates ?? {};
+        if (!result.updated || Object.keys(updates).length === 0) {
+            this.logger?.info?.('[KeywordOptimizationService] No updates to apply');
+            return;
+        }
+        for (const [term, update] of Object.entries(updates)) {
+            try {
+                switch (update.action) {
+                    case 'add': {
+                        const normalizedTerm = term.trim().toLowerCase();
+                        // Check for existing normalized term to avoid duplicates
+                        const existing = learner.getStore().keywords.find(k => k.term.toLowerCase() === normalizedTerm);
+                        if (existing) {
+                            this.logger?.info?.(`[KeywordOptimizationService] ADD skipped: "${term}" already exists as "${existing.term}"`);
+                            break;
+                        }
+                        const weight = update.weight !== undefined
+                            ? Math.max(0.1, Math.min(0.9, update.weight))
+                            : 0.5;
+                        learner.add({ term: normalizedTerm, weight, source: 'llm' });
+                        this.logger?.info?.(`[KeywordOptimizationService] ADD term="${normalizedTerm}" weight=${weight}`);
+                        break;
+                    }
+                    case 'update': {
+                        if (update.weight !== undefined) {
+                            learner.updateWeight(term, update.weight);
+                            this.logger?.info?.(`[KeywordOptimizationService] UPDATE term="${term}" weight=${update.weight}`);
+                        }
+                        break;
+                    }
+                    case 'remove': {
+                        learner.remove(term);
+                        this.logger?.info?.(`[KeywordOptimizationService] REMOVE term="${term}"`);
+                        break;
+                    }
+                }
+            }
+            catch (opErr) {
+                // Log and skip individual operation failures — don't fail the whole batch
+                this.logger?.warn?.(`[KeywordOptimizationService] ${update.action.toUpperCase()} failed for term="${term}": ${String(opErr)}`);
+            }
+        }
+        // H-1: Record confirmed false positives — terms where correctionDetected fired
+        // but trajectory analysis shows user wasn't actually expressing frustration.
+        if (result.fpAnalysisStatus === 'completed' && result.fpTerms && result.fpTerms.length > 0) {
+            // Normalize: trim, lowercase, dedupe, sanity cap
+            const MAX_FP_TERMS = 20;
+            const normalizedFpTerms = [...new Set(result.fpTerms
+                    .map((t) => t.trim().toLowerCase())
+                    .filter((t) => t.length > 0))].slice(0, MAX_FP_TERMS);
+            for (const term of normalizedFpTerms) {
+                try {
+                    learner.recordFalsePositive(term);
+                    this.logger?.info?.(`[KeywordOptimizationService] FP recorded for term="${term}" (weight x0.8)`);
+                }
+                catch (fpErr) {
+                    this.logger?.warn?.(`[KeywordOptimizationService] recordFalsePositive failed for term="${term}": ${String(fpErr)}`);
+                }
+            }
+        }
+    }
+    /**
+     * Builds trajectory history for payload:
+     * - Calls TrajectoryDatabase.listUserTurnsForSession() for recent sessions
+     * - Filters to turns where correctionDetected=true
+     * - Returns last 50 correction events
+     */
+    async buildTrajectoryHistory(sessionIds) {
+        const history = [];
+        const db = TrajectoryRegistry.get(this.workspaceDir);
+        for (const sessionId of sessionIds.slice(0, 10)) { // Last 10 sessions
+            try {
+                const turns = db.listUserTurnsForSession(sessionId);
+                for (const turn of turns) {
+                    if (turn.correctionDetected) {
+                        history.push({
+                            sessionId,
+                            timestamp: turn.createdAt ?? new Date().toISOString(),
+                            term: turn.correctionCue ?? 'unknown',
+                            // Note: rawText is not available from listUserTurnsForSession (privacy: no raw text stored).
+                            // userMessage left empty — trajectory section is used for FPR trend analysis,
+                            // not for understanding user intent (correctionCue term is sufficient).
+                            userMessage: '',
+                        });
+                    }
+                    if (history.length >= 50)
+                        break; // Cap at 50 events
+                }
+            }
+            catch (dbErr) {
+                // Skip individual session DB errors — try remaining sessions
+                this.logger?.warn?.(`[KeywordOptimizationService] Failed to read trajectory for session ${sessionId}: ${String(dbErr)}`);
+            }
+            if (history.length >= 50)
+                break;
+        }
+        return history;
+    }
+    // ── Singleton factory ───────────────────────────────────────────────────
+    static _instances = new Map();
+    static get(stateDir, workspaceDir, logger) {
+        const key = `${stateDir}::${workspaceDir}`;
+        if (!KeywordOptimizationService._instances.has(key)) {
+            KeywordOptimizationService._instances.set(key, new KeywordOptimizationService(stateDir, workspaceDir, logger));
+        }
+        return KeywordOptimizationService._instances.get(key);
+    }
+    static reset() {
+        KeywordOptimizationService._instances.clear();
+    }
+}

package/dist/service/phase3-input-filter.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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
+ */
+/**
+ * Classification for Phase 3 inputs.
+ * - authoritative: Can be used for Phase 3 eligibility decisions
+ * - reference_only: Valid data but not for eligibility (e.g., timeout outcomes)
+ * - rejected: Invalid or corrupt data
+ */
+export type Phase3Classification = 'authoritative' | 'reference_only' | 'rejected';
+export interface Phase3EvolutionInput {
+    id?: string | null;
+    status?: string | null;
+    started_at?: string | null;
+    completed_at?: string | null;
+    resolution?: string | null;
+}
+export interface Phase3EvolutionSample {
+    taskId: string;
+    status: 'pending' | 'in_progress' | 'completed';
+    startedAt: string | null;
+    completedAt: string | null;
+}
+export interface Phase3ReferenceOnlySample {
+    taskId: string;
+    status: string;
+    classification: 'timeout_only' | 'other_reference';
+    reason: string;
+}
+export interface Phase3RejectedEvolutionSample {
+    taskId: string | null;
+    status: string | null;
+    reasons: string[];
+}
+export interface Phase3InputFilterResult {
+    queueTruthReady: boolean;
+    phase3ShadowEligible: boolean;
+    evolution: {
+        eligible: Phase3EvolutionSample[];
+        referenceOnly: Phase3ReferenceOnlySample[];
+        rejected: Phase3RejectedEvolutionSample[];
+    };
+}
+/**
+ * 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 declare function evaluatePhase3Inputs(queue: Phase3EvolutionInput[]): Phase3InputFilterResult;