@principles/core 1.84.0 → 1.86.0

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

@@ -1,8 +1,8 @@
-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 { ArtificerPromptBuilder } from './artificer-prompt-builder.js';
 import { injectRunnerLineageIfAbsent } from './peer-runner-contracts.js';
+import { BasePeerRunner } from '../runner/base-peer-runner.js';
 const DEFAULT_ARTIFICER_RUNNER_OPTIONS = {
     pollIntervalMs: 5_000,
     timeoutMs: 300_000,
@@ -19,117 +19,22 @@ export function resolveArtificerRunnerOptions(options) {
         agentId: options.agentId ?? DEFAULT_ARTIFICER_RUNNER_OPTIONS.agentId,
     };
 }
-export class ArtificerRunner {
-    phase = RunnerPhase.Idle;
-    resolvedOptions;
-    stateManager;
-    runtimeAdapter;
-    eventEmitter;
+// ── ArtificerRunner ──────────────────────────────────────────────────────────
+export class ArtificerRunner 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 = resolveArtificerRunnerOptions(options);
-    }
-    get currentPhase() {
-        return this.phase;
-    }
-    emitArtificerEvent(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: 'artificer',
+            expectedTaskKind: 'artificer',
+            defaultAgentId: 'artificer',
+            resultRefPrefix: 'artificer',
         });
+        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 !== 'artificer') {
-            this.emitArtificerEvent('artificer_wrong_task_kind', taskId, {
-                expectedKind: 'artificer',
-                actualKind: leasedTask.taskKind,
-            });
-            await this.stateManager.markTaskFailed(taskId, 'input_invalid');
-            return {
-                status: 'failed',
-                taskId,
-                errorCategory: 'input_invalid',
-                failureReason: `Task kind must be 'artificer', got '${leasedTask.taskKind}'`,
-                attemptCount: leasedTask.attemptCount,
-            };
-        }
-        this.emitArtificerEvent('artificer_task_leased', taskId, {
-            taskKind: 'artificer',
-            attemptCount: leasedTask.attemptCount,
-        });
-        try {
-            const storeRunId = await this.resolveStoreRunId(taskId);
-            this.phase = RunnerPhase.BuildingContext;
-            const { contextHash, scribeArtifact, sourceScribeArtifactId } = await this.buildContext(taskId);
-            if (!scribeArtifact || !sourceScribeArtifactId) {
-                return this.retryOrFail({
-                    taskId,
-                    task: leasedTask,
-                    errorCategory: 'input_invalid',
-                    failureReason: sourceScribeArtifactId ? 'Scribe dependency artifact not found' : 'Scribe dependency artifact ID not resolved',
-                });
-            }
-            this.emitArtificerEvent('artificer_context_built', taskId, { contextHash });
-            this.phase = RunnerPhase.Invoking;
-            const runHandle = await this.invokeRuntime({ taskId, contextHash, scribeArtifact, sourceScribeArtifactId });
-            this.emitArtificerEvent('artificer_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, sourceScribeArtifactId ?? undefined);
-            if (!validationResult.valid) {
-                return await this.handleValidationError({
-                    taskId,
-                    task: leasedTask,
-                    errors: validationResult.errors,
-                    errorCategory: validationResult.errorCategory,
-                });
-            }
-            this.emitArtificerEvent('artificer_output_validated', taskId, {
-                implementationSummary: output.implementationPlan.summary,
-            });
-            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);
@@ -139,7 +44,7 @@ export class ArtificerRunner {
         const piTask = hydratePITaskRecord(task);
         const deps = piTask?.dependencyTaskIds ?? [];
         if (deps.length === 0) {
-            this.emitArtificerEvent('artificer_no_dependencies', taskId, {});
+            this.emitEvent('no_dependencies', taskId, {});
             return { contextHash: 'empty', scribeArtifact: null, sourceScribeArtifactId: null };
         }
         for (const depId of deps) {
@@ -149,7 +54,7 @@ export class ArtificerRunner {
             if (depTask.taskKind !== 'scribe')
                 continue;
             if (depTask.status !== 'succeeded') {
-                this.emitArtificerEvent('artificer_dependency_not_succeeded', taskId, {
+                this.emitEvent('dependency_not_succeeded', taskId, {
                     depTaskId: depId,
                     depStatus: depTask.status,
                 });
@@ -161,362 +66,183 @@ export class ArtificerRunner {
                 if (!firstArtifact)
                     continue;
                 const artifactRef = firstArtifact.artifactId;
-                this.emitArtificerEvent('artificer_scribe_dep_selected', taskId, {
+                this.emitEvent('scribe_dep_selected', taskId, {
                     depTaskId: depId,
                     artifactId: firstArtifact.artifactId,
                 });
                 return {
-                    contextHash: ArtificerRunner.hashContextRefs([artifactRef]),
+                    contextHash: BasePeerRunner.hashContextRefs([artifactRef]),
                     scribeArtifact: firstArtifact.contentJson,
                     sourceScribeArtifactId: firstArtifact.artifactId,
                 };
             }
         }
-        this.emitArtificerEvent('artificer_no_scribe_artifact', taskId, {});
+        this.emitEvent('no_scribe_artifact', taskId, {});
         return { contextHash: 'empty', scribeArtifact: null, sourceScribeArtifactId: 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;
+    async invokeRuntime(taskId, context) {
+        if (!context.scribeArtifact || !context.sourceScribeArtifactId) {
+            throw new PDRuntimeError('input_invalid', 'Scribe dependency artifact not resolved');
         }
-        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`);
+        let scribeArtifactInput;
+        try {
+            scribeArtifactInput = JSON.parse(context.scribeArtifact);
         }
-        return latestRun.runId;
-    }
-    async invokeRuntime(params) {
-        let parsedScribeArtifact = null;
-        if (params.scribeArtifact) {
-            try {
-                parsedScribeArtifact = JSON.parse(params.scribeArtifact);
-            }
-            catch {
-                parsedScribeArtifact = params.scribeArtifact;
-            }
+        catch {
+            scribeArtifactInput = context.scribeArtifact;
         }
         const builder = new ArtificerPromptBuilder();
         const { message } = builder.buildPrompt({
-            taskId: params.taskId,
-            contextHash: params.contextHash,
-            scribeArtifact: parsedScribeArtifact,
-            sourceScribeArtifactId: params.sourceScribeArtifactId,
+            taskId,
+            contextHash: context.contextHash,
+            scribeArtifact: scribeArtifactInput,
+            sourceScribeArtifactId: context.sourceScribeArtifactId,
         });
-        const startInput = {
+        return this.runtimeAdapter.startRun({
             agentSpec: { agentId: this.resolvedOptions.agentId, schemaVersion: 'v1' },
-            taskRef: { taskId: params.taskId },
+            taskRef: { taskId },
             inputPayload: message,
             contextItems: [],
             outputSchemaRef: 'artificer-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);
+    async validateOutput(output, taskId, context) {
+        const result = await this.validator.validate(output, taskId, context.sourceScribeArtifactId ?? undefined);
+        // Trust-boundary: validator returns `string | undefined` for errorCategory.
+        // Must not `as`-cast; validate at runtime (ERR-001, ERR-005).
+        const rawCategory = result.errorCategory;
+        let errorCategory;
+        if (rawCategory == null) {
+            errorCategory = undefined;
         }
-        let cancelFailed = false;
-        try {
-            await this.runtimeAdapter.cancelRun(runHandle.runId);
+        else if (isPDErrorCategory(rawCategory)) {
+            errorCategory = rawCategory;
         }
-        catch (cancelErr) {
-            cancelFailed = true;
-            this.emitArtificerEvent('artificer_cancel_run_failed', runHandle.runId, {
-                runId: runHandle.runId,
-                errorMessage: cancelErr instanceof Error ? cancelErr.message : String(cancelErr),
-            });
+        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: sourceScribeArtifactId must match buildContext result (ERR-004, ERR-008).
+        if (!context.sourceScribeArtifactId || output.sourceScribeArtifactId !== context.sourceScribeArtifactId) {
+            throw new PDRuntimeError('output_invalid', `sourceScribeArtifactId mismatch: expected ${context.sourceScribeArtifactId ?? '(none)'}, got ${output.sourceScribeArtifactId}`);
         }
-        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.emitArtificerEvent('artificer_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),
+            });
+        }
+        if (lineageHasRejected) {
+            this.emitEvent('lineage_partial', taskId, {
+                runId,
+                resolvedCount: lineageArtifactIds.length,
+                warning: 'Some dependency artifact queries were rejected; lineage may be incomplete',
+            });
         }
-        catch { /* lineage resolution failure is non-fatal */ }
+        // 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.emitArtificerEvent('artificer_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 = `artificer://${ctx.runId}`;
+        // 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.emitArtificerEvent('artificer_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.emitArtificerEvent('artificer_task_succeeded', ctx.taskId, {
-            attemptCount: ctx.task.attemptCount,
+        this.emitEvent('task_succeeded', taskId, {
+            attemptCount: task.attemptCount,
             resultRef,
-            implementationSummary: ctx.output.implementationPlan.summary,
+            implementationSummary: output.implementationPlan.summary,
         });
-        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.emitArtificerEvent('artificer_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.emitArtificerEvent('artificer_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.emitArtificerEvent('artificer_run_failed', taskId, {
-                errorCategory: 'lease_conflict',
-                errorMessage: classified.message,
-            });
-            return {
-                status: 'failed',
-                taskId,
-                errorCategory: 'lease_conflict',
-                failureReason: classified.message,
-                attemptCount: 1,
-            };
-        }
-        this.emitArtificerEvent('artificer_run_failed', taskId, {
-            errorCategory: classified.category,
-            errorMessage: classified.message,
-        });
-        const task = {
-            taskId,
-            taskKind: 'artificer',
-            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 });
-    }
-    async handlePostLeaseError(taskId, task, error) {
-        const classified = this.classifyError(error);
-        this.emitArtificerEvent('artificer_run_failed', taskId, {
-            errorCategory: classified.category,
-            errorMessage: classified.message,
-        });
-        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.emitArtificerEvent('artificer_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.emitArtificerEvent('artificer_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.emitArtificerEvent('artificer_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.emitArtificerEvent('artificer_task_retried', ctx.taskId, {
-                errorCategory: ctx.errorCategory,
-                attemptCount: ctx.task.attemptCount,
-            });
-            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.emitArtificerEvent('artificer_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.emitArtificerEvent('artificer_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,
-        };
-    }
-    PERMANENT_ERROR_CATEGORIES = new Set(Object.freeze(['storage_unavailable', 'workspace_invalid', 'capability_missing', 'cancelled', 'input_invalid', 'output_invalid']));
-    isPermanentError(category) {
-        return this.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) };
-    }
+    // ── 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
-    mapRunStatusToErrorCategory(status) {
-        switch (status) {
-            case 'failed': return 'execution_failed';
-            case 'timed_out': return 'timeout';
-            case 'cancelled': return 'cancelled';
-            default: return 'execution_failed';
-        }
-    }
-    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
-    sleep(ms) {
-        return new Promise((resolve) => setTimeout(resolve, ms));
+    postFetchTransform(taskId, untrustedOutput) {
+        injectRunnerLineageIfAbsent(untrustedOutput, 'taskId', taskId);
+    }
+    emitSuccessTelemetry(taskId, output) {
+        this.emitEvent('implementation_plan_generated', taskId, {
+            implementationSummary: output.implementationPlan.summary,
+            targetSurface: output.implementationPlan.targetSurface,
+            confidence: output.implementationPlan.confidence,
+        });
     }
 }
 export { DEFAULT_ARTIFICER_RUNNER_OPTIONS };