@principles/core 1.85.0 → 1.87.0

package/dist/runtime-v2/internalization/evaluator-runner.js

@@ -1,9 +1,9 @@
-import { PDRuntimeError } from '../error-categories.js';
+import { PDRuntimeError, isPDErrorCategory } from '../error-categories.js';
 import { hydratePITaskRecord } from './pitask-metadata.js';
-import { RunnerPhase } from '../runner/runner-phase.js';
 import { EvaluatorPromptBuilder } from './evaluator-prompt-builder.js';
 import { injectRunnerLineageIfAbsent } from './peer-runner-contracts.js';
-const DEFAULT_EVALUATOR_RUNNER_OPTIONS = {
+import { BasePeerRunner } from '../runner/base-peer-runner.js';
+export const DEFAULT_EVALUATOR_RUNNER_OPTIONS = {
     pollIntervalMs: 5_000,
     timeoutMs: 300_000,
     defaultMaxAttempts: 3,
@@ -19,119 +19,22 @@ export function resolveEvaluatorRunnerOptions(options) {
         agentId: options.agentId ?? DEFAULT_EVALUATOR_RUNNER_OPTIONS.agentId,
     };
 }
-const EVALUATOR_PERMANENT_ERROR_CATEGORIES = new Set([
-    'storage_unavailable', 'workspace_invalid', 'capability_missing', 'cancelled', 'input_invalid', 'output_invalid',
-]);
-export class EvaluatorRunner {
-    phase = RunnerPhase.Idle;
-    resolvedOptions;
-    stateManager;
-    runtimeAdapter;
-    eventEmitter;
+// ── EvaluatorRunner ───────────────────────────────────────────────────────────
+export class EvaluatorRunner extends BasePeerRunner {
     validator;
-    artifactStore;
     constructor(deps, options) {
-        this.stateManager = deps.stateManager;
-        this.runtimeAdapter = deps.runtimeAdapter;
-        this.eventEmitter = deps.eventEmitter;
-        this.validator = deps.validator;
-        this.artifactStore = deps.artifactStore;
-        this.resolvedOptions = resolveEvaluatorRunnerOptions(options);
-    }
-    get currentPhase() {
-        return this.phase;
-    }
-    emitEvaluatorEvent(eventType, taskId, payload) {
-        this.eventEmitter.emitTelemetry({
-            eventType: eventType,
-            traceId: taskId,
-            timestamp: new Date().toISOString(),
-            sessionId: this.resolvedOptions.owner,
-            agentId: this.resolvedOptions.agentId,
-            payload,
+        super(deps, options, {
+            runnerName: 'evaluator',
+            expectedTaskKind: 'evaluator',
+            defaultAgentId: 'evaluator',
+            resultRefPrefix: 'evaluator',
         });
+        this.validator = deps.validator;
     }
-    async run(taskId) {
-        this.phase = RunnerPhase.Idle;
-        let leasedTask;
-        try {
-            leasedTask = await this.stateManager.acquireLease({
-                taskId,
-                owner: this.resolvedOptions.owner,
-                runtimeKind: this.resolvedOptions.runtimeKind,
-            });
-        }
-        catch (error) {
-            return await this.handleLeaseOrPhaseError(taskId, error);
-        }
-        if (leasedTask.taskKind !== 'evaluator') {
-            this.emitEvaluatorEvent('evaluator_wrong_task_kind', taskId, {
-                expectedKind: 'evaluator',
-                actualKind: leasedTask.taskKind,
-            });
-            return this.retryOrFail({
-                taskId,
-                task: leasedTask,
-                errorCategory: 'input_invalid',
-                failureReason: `Task kind must be 'evaluator', got '${leasedTask.taskKind}'`,
-            });
-        }
-        this.emitEvaluatorEvent('evaluator_task_leased', taskId, {
-            taskKind: 'evaluator',
-            attemptCount: leasedTask.attemptCount,
-        });
-        try {
-            const storeRunId = await this.resolveStoreRunId(taskId);
-            this.phase = RunnerPhase.BuildingContext;
-            const { contextHash, artificerArtifact, sourceArtificerArtifactId } = await this.buildContext(taskId);
-            if (!artificerArtifact || !sourceArtificerArtifactId) {
-                return this.retryOrFail({
-                    taskId,
-                    task: leasedTask,
-                    errorCategory: 'input_invalid',
-                    failureReason: sourceArtificerArtifactId ? 'Artificer dependency artifact not found' : 'Artificer dependency artifact ID not resolved',
-                });
-            }
-            this.emitEvaluatorEvent('evaluator_context_built', taskId, { contextHash });
-            this.phase = RunnerPhase.Invoking;
-            const runHandle = await this.invokeRuntime({ taskId, contextHash, artificerArtifact, sourceArtificerArtifactId });
-            this.emitEvaluatorEvent('evaluator_run_started', taskId, {
-                runtimeKind: this.resolvedOptions.runtimeKind,
-            });
-            this.phase = RunnerPhase.Polling;
-            const finalStatus = await this.pollUntilTerminal(runHandle);
-            if (finalStatus.status !== 'succeeded') {
-                return await this.handleRuntimeFailure(taskId, leasedTask, finalStatus);
-            }
-            this.phase = RunnerPhase.FetchingOutput;
-            const output = await this.fetchAndParseOutput(runHandle.runId);
-            // Re-inject taskId if stripped by stripLineageFields (PRI-272 / ERR-008).
-            injectRunnerLineageIfAbsent(output, 'taskId', taskId);
-            this.phase = RunnerPhase.Validating;
-            const validationResult = await this.validator.validate(output, taskId, sourceArtificerArtifactId ?? undefined);
-            if (!validationResult.valid) {
-                return await this.handleValidationError({
-                    taskId,
-                    task: leasedTask,
-                    errors: validationResult.errors,
-                    errorCategory: validationResult.errorCategory,
-                });
-            }
-            this.emitEvaluatorEvent('evaluator_output_validated', taskId, {
-                evaluationDecision: output.evaluation.decision,
-                evaluationScore: output.evaluation.score,
-            });
-            return await this.succeedTask({
-                taskId,
-                runId: storeRunId,
-                output,
-                task: leasedTask,
-                contextHash,
-            });
-        }
-        catch (error) {
-            return await this.handlePostLeaseError(taskId, leasedTask, error);
-        }
+    // ── Abstract implementations ────────────────────────────────────────────────
+    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+    get permanentErrorCategories() {
+        return new Set(['storage_unavailable', 'workspace_invalid', 'capability_missing', 'cancelled', 'input_invalid', 'output_invalid']);
     }
     async buildContext(taskId) {
         const task = await this.stateManager.getTask(taskId);
@@ -141,8 +44,8 @@ export class EvaluatorRunner {
         const piTask = hydratePITaskRecord(task);
         const deps = piTask?.dependencyTaskIds ?? [];
         if (deps.length === 0) {
-            this.emitEvaluatorEvent('evaluator_no_dependencies', taskId, {});
-            return { contextHash: 'empty', artificerArtifact: null, sourceArtificerArtifactId: null };
+            this.emitEvent('no_dependencies', taskId, {});
+            throw new PDRuntimeError('input_invalid', 'Artificer dependency artifact ID not resolved');
         }
         for (const depId of deps) {
             const depTask = await this.stateManager.getTask(depId);
@@ -151,7 +54,7 @@ export class EvaluatorRunner {
             if (depTask.taskKind !== 'artificer')
                 continue;
             if (depTask.status !== 'succeeded') {
-                this.emitEvaluatorEvent('evaluator_dependency_not_succeeded', taskId, {
+                this.emitEvent('dependency_not_succeeded', taskId, {
                     depTaskId: depId,
                     depStatus: depTask.status,
                 });
@@ -163,170 +66,149 @@ export class EvaluatorRunner {
                 if (!firstArtifact)
                     continue;
                 const artifactRef = firstArtifact.artifactId;
-                this.emitEvaluatorEvent('evaluator_artificer_dep_selected', taskId, {
+                this.emitEvent('artificer_dep_selected', taskId, {
                     depTaskId: depId,
                     artifactId: firstArtifact.artifactId,
                 });
                 return {
-                    contextHash: EvaluatorRunner.hashContextRefs([artifactRef]),
+                    contextHash: BasePeerRunner.hashContextRefs([artifactRef]),
                     artificerArtifact: firstArtifact.contentJson,
                     sourceArtificerArtifactId: firstArtifact.artifactId,
                 };
             }
         }
-        this.emitEvaluatorEvent('evaluator_no_artificer_artifact', taskId, {});
-        return { contextHash: 'empty', artificerArtifact: null, sourceArtificerArtifactId: null };
-    }
-    static hashContextRefs(refs) {
-        if (refs.length === 0)
-            return 'empty';
-        const str = refs.join('|');
-        let hash = 0;
-        for (let i = 0; i < str.length; i++) {
-            hash = (Math.imul(31, hash) + str.charCodeAt(i)) | 0;
-        }
-        return `ctx-${Math.abs(hash).toString(16)}`;
-    }
-    async resolveStoreRunId(taskId) {
-        const runs = await this.stateManager.getRunsByTask(taskId);
-        const latestRun = runs[runs.length - 1];
-        if (!latestRun) {
-            throw new PDRuntimeError('execution_failed', `No run records found for task ${taskId} after lease acquisition`);
-        }
-        return latestRun.runId;
+        this.emitEvent('no_artificer_artifact', taskId, {});
+        throw new PDRuntimeError('input_invalid', 'Artificer dependency artifact not found');
     }
-    async invokeRuntime(params) {
+    async invokeRuntime(taskId, context) {
         let parsedArtificerArtifact = null;
-        if (params.artificerArtifact) {
+        if (context.artificerArtifact) {
             try {
-                parsedArtificerArtifact = JSON.parse(params.artificerArtifact);
+                parsedArtificerArtifact = JSON.parse(context.artificerArtifact);
             }
             catch {
-                parsedArtificerArtifact = params.artificerArtifact;
+                parsedArtificerArtifact = context.artificerArtifact;
             }
         }
         const builder = new EvaluatorPromptBuilder();
         const { message } = builder.buildPrompt({
-            taskId: params.taskId,
-            contextHash: params.contextHash,
+            taskId,
+            contextHash: context.contextHash,
             artificerArtifact: parsedArtificerArtifact,
-            sourceArtificerArtifactId: params.sourceArtificerArtifactId,
+            sourceArtificerArtifactId: context.sourceArtificerArtifactId ?? '',
         });
-        const startInput = {
+        return this.runtimeAdapter.startRun({
             agentSpec: { agentId: this.resolvedOptions.agentId, schemaVersion: 'v1' },
-            taskRef: { taskId: params.taskId },
+            taskRef: { taskId },
             inputPayload: message,
             contextItems: [],
             outputSchemaRef: 'evaluator-output-v1',
             timeoutMs: this.resolvedOptions.timeoutMs,
-        };
-        return this.runtimeAdapter.startRun(startInput);
+        });
     }
-    async pollUntilTerminal(runHandle) {
-        const deadline = Date.now() + this.resolvedOptions.timeoutMs;
-        const terminalStatuses = ['succeeded', 'failed', 'timed_out', 'cancelled'];
-        while (Date.now() < deadline) {
-            const status = await this.runtimeAdapter.pollRun(runHandle.runId);
-            if (terminalStatuses.includes(status.status)) {
-                return status;
-            }
-            await this.sleep(this.resolvedOptions.pollIntervalMs);
-        }
-        try {
-            const finalPoll = await this.runtimeAdapter.pollRun(runHandle.runId);
-            if (terminalStatuses.includes(finalPoll.status)) {
-                return finalPoll;
-            }
-        }
-        catch { /* fall through to cancel/timeout */ }
-        let cancelFailed = false;
-        try {
-            await this.runtimeAdapter.cancelRun(runHandle.runId);
-        }
-        catch (cancelErr) {
-            cancelFailed = true;
-            this.emitEvaluatorEvent('evaluator_cancel_run_failed', runHandle.runId, {
-                runId: runHandle.runId,
-                errorMessage: cancelErr instanceof Error ? cancelErr.message : String(cancelErr),
-            });
+    async validateOutput(output, taskId, context) {
+        const result = await this.validator.validate(output, taskId, context.sourceArtificerArtifactId ?? undefined);
+        // Trust-boundary: validator is an injected dependency returning `string | undefined`
+        // for errorCategory. We must not `as`-cast; validate at runtime (ERR-001, ERR-005).
+        const rawCategory = result.errorCategory;
+        let errorCategory;
+        if (rawCategory == null) {
+            errorCategory = undefined;
+        }
+        else if (isPDErrorCategory(rawCategory)) {
+            errorCategory = rawCategory;
+        }
+        else {
+            // Invalid errorCategory from validator — fail loud, do not pass through
+            return {
+                valid: false,
+                errors: [...result.errors, `invalid errorCategory: ${rawCategory}`],
+                errorCategory: 'output_invalid',
+            };
         }
-        const cancelNote = cancelFailed ? ' (cancelRun also failed)' : '';
-        throw new PDRuntimeError('timeout', `Run ${runHandle.runId} timed out after ${this.resolvedOptions.timeoutMs}ms${cancelNote}`);
+        return {
+            valid: result.valid,
+            errors: result.errors,
+            errorCategory,
+        };
     }
-    async fetchAndParseOutput(runId) {
-        const result = await this.runtimeAdapter.fetchOutput(runId);
-        if (!result || !result.payload) {
-            throw new PDRuntimeError('output_invalid', `No output available for run ${runId}`);
+    // eslint-disable-next-line @typescript-eslint/max-params
+    async succeedTask(taskId, runId, output, task, contextHash, context) {
+        // Lineage consistency: sourceArtificerArtifactId must match buildContext result (ERR-004).
+        if (context.sourceArtificerArtifactId && output.sourceArtificerArtifactId !== context.sourceArtificerArtifactId) {
+            throw new PDRuntimeError('output_invalid', `sourceArtificerArtifactId mismatch: expected ${context.sourceArtificerArtifactId}, got ${output.sourceArtificerArtifactId}`);
         }
-        const payload = result.payload;
-        if (typeof payload !== 'object' || payload === null) {
-            throw new PDRuntimeError('output_invalid', `Output payload is not an object for run ${runId}`);
-        }
-        if (typeof payload.evaluation !== 'object' || payload.evaluation === null) {
-            throw new PDRuntimeError('output_invalid', `Output payload missing evaluation object for run ${runId}`);
-        }
-        return result.payload;
-    }
-    async succeedTask(ctx) {
+        // Store output before marking succeeded
         try {
-            await this.stateManager.updateRunOutput(ctx.runId, JSON.stringify(ctx.output));
+            await this.stateManager.updateRunOutput(runId, JSON.stringify(output));
         }
         catch (updateErr) {
-            this.emitEvaluatorEvent('evaluator_update_output_failed', ctx.taskId, {
-                runId: ctx.runId,
+            this.emitEvent('update_output_failed', taskId, {
+                runId,
                 errorMessage: updateErr instanceof Error ? updateErr.message : String(updateErr),
             });
             throw updateErr;
         }
-        const artifactId = `pi-art-${ctx.taskId}-${ctx.runId}`;
-        const now = new Date().toISOString();
+        // Resolve lineage artifact IDs
         let lineageArtifactIds = [];
+        let lineageHasRejected = false;
         try {
-            const piTask = hydratePITaskRecord(ctx.task);
-            const deps = piTask?.dependencyTaskIds ?? [];
-            const results = await Promise.allSettled(deps.map((depId) => this.artifactStore.listBySourceTaskId(depId)));
-            for (const result of results) {
-                if (result.status === 'fulfilled') {
-                    for (const artifact of result.value) {
-                        lineageArtifactIds.push(artifact.artifactId);
-                    }
-                }
-            }
+            const lineageResult = await this.resolveLineageArtifactIds(taskId);
+            lineageArtifactIds = lineageResult.ids;
+            lineageHasRejected = lineageResult.hasRejected;
+        }
+        catch (lineageErr) {
+            this.emitEvent('lineage_resolve_failed', taskId, {
+                runId,
+                errorMessage: lineageErr instanceof Error ? lineageErr.message : String(lineageErr),
+            });
         }
-        catch { /* lineage resolution failure is non-fatal */ }
+        if (lineageHasRejected) {
+            this.emitEvent('lineage_partial', taskId, {
+                runId,
+                resolvedCount: lineageArtifactIds.length,
+                warning: 'Some dependency artifact queries were rejected; lineage may be incomplete',
+            });
+        }
+        // Write PIArtifact via artifactStore (idempotent upsert)
+        const artifactId = `pi-art-${taskId}-${runId}`;
+        const now = new Date().toISOString();
         try {
             await this.artifactStore.upsertArtifact({
                 artifactId,
                 artifactKind: 'principle',
-                sourceTaskId: ctx.taskId,
+                sourceTaskId: taskId,
                 lineageArtifactIds,
                 validationStatus: 'pending',
-                contentJson: JSON.stringify(ctx.output),
+                contentJson: JSON.stringify(output),
                 createdAt: now,
                 updatedAt: now,
             });
         }
         catch (artifactErr) {
-            this.emitEvaluatorEvent('evaluator_artifact_write_failed', ctx.taskId, {
-                runId: ctx.runId,
+            this.emitEvent('artifact_write_failed', taskId, {
+                runId,
                 errorMessage: artifactErr instanceof Error ? artifactErr.message : String(artifactErr),
             });
             return this.retryOrFail({
-                taskId: ctx.taskId,
-                task: ctx.task,
+                taskId,
+                task,
                 errorCategory: 'artifact_commit_failed',
                 failureReason: `PIArtifact write failed: ${artifactErr instanceof Error ? artifactErr.message : String(artifactErr)}`,
             });
         }
-        const resultRef = `evaluator://${ctx.runId}`;
-        if (ctx.output.evaluation.decision === 'approved') {
-            const principleArtifactId = await this.resolvePrincipleBearerArtifact(ctx.output, ctx.taskId);
+        // ── Evaluator-specific: validate principle-bearing Scribe artifact ──
+        // This is the critical business logic: approved evaluator must validate
+        // the Scribe principle artifact, NOT the Artificer plan artifact.
+        if (output.evaluation.decision === 'approved') {
+            const principleArtifactId = await this.resolvePrincipleBearerArtifact(output, taskId);
             if (principleArtifactId) {
                 try {
                     const updated = await this.artifactStore.updateValidationStatus(principleArtifactId, 'validated');
                     if (!updated) {
-                        this.emitEvaluatorEvent('evaluator_source_validation_update_not_found', ctx.taskId, {
-                            runId: ctx.runId,
+                        // updateValidationStatus returned false — fail loud with structured telemetry (ERR-018)
+                        this.emitEvent('source_validation_update_not_found', taskId, {
+                            runId,
                             sourceArtifactId: principleArtifactId,
                             reason: 'principle_artifact_not_found_in_store',
                             nextAction: 'verify_artifact_lineage_and_store_consistency',
@@ -334,228 +216,88 @@ export class EvaluatorRunner {
                     }
                 }
                 catch (updateErr) {
-                    this.emitEvaluatorEvent('evaluator_source_validation_update_failed', ctx.taskId, {
-                        runId: ctx.runId,
+                    this.emitEvent('source_validation_update_failed', taskId, {
+                        runId,
                         sourceArtifactId: principleArtifactId,
                         errorMessage: updateErr instanceof Error ? updateErr.message : String(updateErr),
                     });
                 }
             }
         }
+        // Mark task succeeded
+        const resultRef = `${this.config.resultRefPrefix}://${runId}`;
         try {
-            await this.stateManager.markTaskSucceeded(ctx.taskId, resultRef);
+            await this.stateManager.markTaskSucceeded(taskId, resultRef);
         }
         catch (stateErr) {
-            this.emitEvaluatorEvent('evaluator_mark_succeeded_failed', ctx.taskId, {
-                taskId: ctx.taskId,
-                runId: ctx.runId,
+            this.emitEvent('mark_succeeded_failed', taskId, {
+                taskId,
+                runId,
                 errorMessage: stateErr instanceof Error ? stateErr.message : String(stateErr),
             });
             throw stateErr;
         }
-        this.emitEvaluatorEvent('evaluator_task_succeeded', ctx.taskId, {
-            attemptCount: ctx.task.attemptCount,
+        this.emitEvent('task_succeeded', taskId, {
+            attemptCount: task.attemptCount,
             resultRef,
-            evaluationDecision: ctx.output.evaluation.decision,
-            evaluationScore: ctx.output.evaluation.score,
+            evaluationDecision: output.evaluation.decision,
+            evaluationScore: output.evaluation.score,
         });
-        this.phase = RunnerPhase.Completed;
         return {
             status: 'succeeded',
-            taskId: ctx.taskId,
-            runId: ctx.runId,
+            taskId,
+            runId,
             artifactId,
             resultRef,
-            contextHash: ctx.contextHash,
-            output: ctx.output,
-            attemptCount: ctx.task.attemptCount,
+            contextHash,
+            output,
+            attemptCount: task.attemptCount,
         };
     }
-    async handleRuntimeFailure(taskId, task, runStatus) {
-        const errorCategory = this.mapRunStatusToErrorCategory(runStatus.status);
-        this.emitEvaluatorEvent('evaluator_run_failed', taskId, {
-            runStatus: runStatus.status,
-            errorCategory,
-        });
-        return this.retryOrFail({
-            taskId,
-            task,
-            errorCategory,
-            failureReason: `Runtime execution ended with status: ${runStatus.status}`,
-        });
-    }
-    async handleValidationError(ctx) {
-        const category = (ctx.errorCategory ?? 'output_invalid');
-        this.emitEvaluatorEvent('evaluator_output_invalid', ctx.taskId, {
-            errorCount: ctx.errors.length,
-            errorCategory: category,
-        });
-        return this.retryOrFail({
-            taskId: ctx.taskId,
-            task: ctx.task,
-            errorCategory: category,
-            failureReason: `Validation failed: ${ctx.errors.join('; ')}`,
-        });
-    }
-    async handleLeaseOrPhaseError(taskId, error) {
-        const classified = this.classifyError(error);
-        if (classified.category === 'lease_conflict') {
-            this.emitEvaluatorEvent('evaluator_run_failed', taskId, {
-                errorCategory: 'lease_conflict',
-                errorMessage: classified.message,
-            });
-            return {
-                status: 'failed',
-                taskId,
-                errorCategory: 'lease_conflict',
-                failureReason: classified.message,
-                attemptCount: 1,
-            };
-        }
-        this.emitEvaluatorEvent('evaluator_run_failed', taskId, {
-            errorCategory: classified.category,
-            errorMessage: classified.message,
-        });
-        const task = {
-            taskId,
-            taskKind: 'evaluator',
-            status: 'leased',
-            createdAt: new Date().toISOString(),
-            updatedAt: new Date().toISOString(),
-            attemptCount: 1,
-            maxAttempts: this.resolvedOptions.defaultMaxAttempts,
-        };
-        return this.retryOrFail({ taskId, task, errorCategory: classified.category, failureReason: classified.message });
+    // ── Optional hooks ──────────────────────────────────────────────────────────
+    /**
+     * Re-inject taskId if stripped by stripLineageFields (PRI-272 / ERR-008).
+     * Only fill when absent via Object.hasOwn — present-but-falsy values
+     * must reach validation and fail loud (Runtime Contract Rule 3).
+     */
+    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+    postFetchTransform(taskId, untrustedOutput) {
+        injectRunnerLineageIfAbsent(untrustedOutput, 'taskId', taskId);
     }
-    async handlePostLeaseError(taskId, task, error) {
-        const classified = this.classifyError(error);
-        this.emitEvaluatorEvent('evaluator_run_failed', taskId, {
-            errorCategory: classified.category,
-            errorMessage: classified.message,
+    emitSuccessTelemetry(taskId, output) {
+        this.emitEvent('decision_recorded', taskId, {
+            evaluationDecision: output.evaluation.decision,
+            evaluationScore: output.evaluation.score,
         });
-        return this.retryOrFail({ taskId, task, errorCategory: classified.category, failureReason: classified.message });
     }
-    async retryOrFail(ctx) {
-        if (this.isPermanentError(ctx.errorCategory)) {
-            try {
-                await this.stateManager.markTaskFailed(ctx.taskId, ctx.errorCategory);
-            }
-            catch (stateErr) {
-                this.emitEvaluatorEvent('evaluator_mark_failed_error', ctx.taskId, {
-                    errorCategory: 'storage_unavailable',
-                    attemptCount: ctx.task.attemptCount,
-                    errorMessage: stateErr instanceof Error ? stateErr.message : String(stateErr),
-                });
-                return {
-                    status: 'failed',
-                    taskId: ctx.taskId,
-                    errorCategory: 'storage_unavailable',
-                    failureReason: `State manager error: ${ctx.failureReason}`,
-                    attemptCount: ctx.task.attemptCount,
-                };
-            }
-            this.emitEvaluatorEvent('evaluator_task_failed', ctx.taskId, {
-                errorCategory: ctx.errorCategory,
-                attemptCount: ctx.task.attemptCount,
-                failureReason: ctx.failureReason,
-            });
-            this.phase = RunnerPhase.Failed;
-            return {
-                status: 'failed',
-                taskId: ctx.taskId,
-                errorCategory: ctx.errorCategory,
-                failureReason: ctx.failureReason,
-                attemptCount: ctx.task.attemptCount,
-            };
-        }
-        const shouldRetry = this.stateManager.getRetryPolicy().shouldRetry(ctx.task);
-        if (shouldRetry) {
-            try {
-                await this.stateManager.markTaskRetryWait(ctx.taskId, ctx.errorCategory);
-            }
-            catch (stateErr) {
-                this.emitEvaluatorEvent('evaluator_mark_retry_error', ctx.taskId, {
-                    errorCategory: 'storage_unavailable',
-                    attemptCount: ctx.task.attemptCount,
-                    errorMessage: stateErr instanceof Error ? stateErr.message : String(stateErr),
-                });
-                return {
-                    status: 'failed',
-                    taskId: ctx.taskId,
-                    errorCategory: 'storage_unavailable',
-                    failureReason: `State manager error: ${ctx.failureReason}`,
-                    attemptCount: ctx.task.attemptCount,
-                };
-            }
-            this.emitEvaluatorEvent('evaluator_task_retried', ctx.taskId, {
-                errorCategory: ctx.errorCategory,
-                attemptCount: ctx.task.attemptCount,
+    /**
+     * Check lineage strip contract after validation passes.
+     * Validates sourceTrace.scribeArtifactId consistency (ERR-004, ERR-008).
+     */
+    checkLineageIntegrity(taskId, output) {
+        // sourceTrace.artificerArtifactId must match sourceArtificerArtifactId
+        if (output.sourceTrace.artificerArtifactId !== output.sourceArtificerArtifactId) {
+            this.emitEvent('lineage_integrity_violation', taskId, {
+                sourceArtificerArtifactId: output.sourceArtificerArtifactId,
+                traceArtificerArtifactId: output.sourceTrace.artificerArtifactId,
+                reason: 'sourceArtificerArtifactId_and_sourceTrace_artificerArtifactId_mismatch',
             });
-            this.phase = RunnerPhase.RetryWaiting;
-            return {
-                status: 'retried',
-                taskId: ctx.taskId,
-                errorCategory: ctx.errorCategory,
-                failureReason: ctx.failureReason,
-                attemptCount: ctx.task.attemptCount,
-            };
-        }
-        try {
-            await this.stateManager.markTaskFailed(ctx.taskId, 'max_attempts_exceeded');
-        }
-        catch (stateErr) {
-            this.emitEvaluatorEvent('evaluator_mark_failed_error', ctx.taskId, {
-                errorCategory: 'storage_unavailable',
-                attemptCount: ctx.task.attemptCount,
-                errorMessage: stateErr instanceof Error ? stateErr.message : String(stateErr),
-            });
-            return {
-                status: 'failed',
-                taskId: ctx.taskId,
-                errorCategory: 'storage_unavailable',
-                failureReason: `State manager error: ${ctx.failureReason}`,
-                attemptCount: ctx.task.attemptCount,
-            };
-        }
-        this.emitEvaluatorEvent('evaluator_task_failed', ctx.taskId, {
-            errorCategory: 'max_attempts_exceeded',
-            attemptCount: ctx.task.attemptCount,
-            failureReason: `Max attempts exceeded: ${ctx.failureReason}`,
-        });
-        this.phase = RunnerPhase.Failed;
-        return {
-            status: 'failed',
-            taskId: ctx.taskId,
-            errorCategory: 'max_attempts_exceeded',
-            failureReason: `Max attempts exceeded: ${ctx.failureReason}`,
-            attemptCount: ctx.task.attemptCount,
-        };
-    }
-    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
-    isPermanentError(category) {
-        return EVALUATOR_PERMANENT_ERROR_CATEGORIES.has(category);
-    }
-    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
-    classifyError(error) {
-        if (error instanceof PDRuntimeError) {
-            return { category: error.category, message: error.message };
-        }
-        if (error instanceof Error) {
-            return { category: 'execution_failed', message: error.message };
-        }
-        return { category: 'execution_failed', message: String(error) };
-    }
-    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
-    mapRunStatusToErrorCategory(status) {
-        switch (status) {
-            case 'failed': return 'execution_failed';
-            case 'timed_out': return 'timeout';
-            case 'cancelled': return 'cancelled';
-            default: return 'execution_failed';
         }
     }
+    // ── Evaluator-specific: principle bearer resolution ─────────────────────────
+    /**
+     * Resolve the principle-bearing artifact that the evaluator should validate.
+     *
+     * Strategy 1: Use scribeArtifactId from sourceTrace (the Scribe artifact
+     * carries principleDraft).
+     * Strategy 2: Search lineage for principle-kind artifacts with principleDraft.
+     * Strategy 3: No principle-bearing artifact found → telemetry, return null.
+     *
+     * Ambiguous candidates (more than 1) → fail loud with telemetry, return null.
+     * Never silently pick the first candidate (ERR-018, ERR-019).
+     */
     async resolvePrincipleBearerArtifact(output, taskId) {
-        // Strategy 1: Use scribeArtifactId from sourceTrace (the Scribe artifact carries principleDraft)
+        // Strategy 1: Use scribeArtifactId from sourceTrace
         const scribeArtifactId = output.sourceTrace?.scribeArtifactId;
         if (typeof scribeArtifactId === 'string' && scribeArtifactId.trim() !== '') {
             const scribeArtifact = await this.artifactStore.getArtifactById(scribeArtifactId);
@@ -563,13 +305,13 @@ export class EvaluatorRunner {
                 return scribeArtifactId;
             }
             // Scribe artifact not found or wrong kind — fall through to lineage search
-            this.emitEvaluatorEvent('evaluator_scribe_artifact_not_principle', taskId, {
+            this.emitEvent('scribe_artifact_not_principle', taskId, {
                 scribeArtifactId,
                 actualKind: scribeArtifact?.artifactKind ?? 'not_found',
             });
         }
         // Strategy 2: Search lineage for all principle-kind artifacts with principleDraft content
-        const lineageArtifactIds = await this.resolveLineageArtifactIds(taskId);
+        const { ids: lineageArtifactIds } = await this.resolveLineageArtifactIds(taskId);
         const candidates = [];
         for (const lineageId of lineageArtifactIds) {
             const artifact = await this.artifactStore.getArtifactById(lineageId);
@@ -586,15 +328,16 @@ export class EvaluatorRunner {
             return only ?? null;
         }
         if (candidates.length > 1) {
-            this.emitEvaluatorEvent('evaluator_principle_bearer_ambiguous', taskId, {
+            // Ambiguous — fail loud, do NOT silently pick first (ERR-018)
+            this.emitEvent('principle_bearer_ambiguous', taskId, {
                 candidateArtifactIds: candidates,
                 reason: 'multiple_principle_bearing_artifacts_in_lineage',
                 nextAction: 'disambiguate_principle_source_or_fix_lineage',
             });
             return null;
         }
-        // Strategy 3: Fallback — no principle-bearing artifact found
-        this.emitEvaluatorEvent('evaluator_no_principle_bearer_found', taskId, {
+        // Strategy 3: No principle-bearing artifact found
+        this.emitEvent('no_principle_bearer_found', taskId, {
             runId: output.taskId,
             scribeArtifactId: scribeArtifactId ?? 'not_provided',
             lineageCount: lineageArtifactIds.length,
@@ -603,28 +346,10 @@ export class EvaluatorRunner {
         });
         return null;
     }
-    async resolveLineageArtifactIds(taskId) {
-        try {
-            const task = await this.stateManager.getTask(taskId);
-            if (!task)
-                return [];
-            const piTask = hydratePITaskRecord(task);
-            const deps = piTask?.dependencyTaskIds ?? [];
-            const results = await Promise.allSettled(deps.map((depId) => this.artifactStore.listBySourceTaskId(depId)));
-            const ids = [];
-            for (const result of results) {
-                if (result.status === 'fulfilled') {
-                    for (const artifact of result.value) {
-                        ids.push(artifact.artifactId);
-                    }
-                }
-            }
-            return ids;
-        }
-        catch {
-            return [];
-        }
-    }
+    /**
+     * Check if an artifact's contentJson contains principle-bearing content.
+     * Uses Object.hasOwn (ERR-013) and runtime type checks (ERR-001, ERR-005).
+     */
     // eslint-disable-next-line @typescript-eslint/class-methods-use-this
     hasPrincipleDraftContent(contentJson) {
         try {
@@ -654,10 +379,5 @@ export class EvaluatorRunner {
     static isRecord(value) {
         return value !== null && typeof value === 'object' && !Array.isArray(value);
     }
-    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
-    sleep(ms) {
-        return new Promise((resolve) => setTimeout(resolve, ms));
-    }
 }
-export { DEFAULT_EVALUATOR_RUNNER_OPTIONS };
 //# sourceMappingURL=evaluator-runner.js.map