@jinn-network/client 0.1.2 → 0.1.3-canary.2d6b2676

package/dist/harnesses/engine/engine.js

@@ -0,0 +1,1203 @@
+/**
+ * Harness engine — main TaskEngine class.
+ *
+ * §6.3, §6.5 of spec/2026-04-17-portfolio-v0-design.md
+ *
+ * Orchestrates the state machine lifecycle for each observed task.
+ * Transition method bodies are stubs; subsequent tasks fill them in.
+ */
+import { join } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { TaskRunPersistence } from './persistence.js';
+import { TaskRunState, MissingEvidenceHashError } from './state.js';
+import { executeTwoLayerClaim, releaseClaimedNotStarted, } from './claim.js';
+import { provisionWorkingDir, provisionImplStateDir, walkArtifacts, uploadArtifacts, } from './packaging.js';
+import { assembleAndSignEnvelope, } from './envelope-assembly.js';
+import { deliverAndClaim, } from './delivery.js';
+import { SkippableError } from '../types.js';
+import { submitEvaluatorFeedback } from '../../erc8004/index.js';
+import { TrajectoryCollector, emitTrajectory } from '../../trajectory/index.js';
+import { buildInfo } from '../../build-info.js';
+// ── Sentinel error ────────────────────────────────────────────────────────────
+export class NotImplementedError extends Error {
+    transitionName;
+    constructor(transitionName) {
+        super(`[NotImplemented] ${transitionName} — fill in via subsequent task`);
+        this.name = 'NotImplementedError';
+        this.transitionName = transitionName;
+    }
+}
+// ── TaskEngine ─────────────────────────────────────────────────────────
+export class TaskEngine {
+    persistence;
+    paths;
+    claimDeps;
+    packagingDeps;
+    envelopeDeps;
+    deliveryDeps;
+    implRegistry;
+    solverNetRegistry;
+    identityPublisher;
+    reputationFeedback;
+    operatorConfig;
+    /** Local SQLite-backed store; used to emit `restoration-result` /
+     *  `evaluation-verdict` artifact rows when a cycle completes via a
+     *  deterministic impl (the legacy claude/MCP path writes them itself). */
+    store;
+    // Transient storage for impl output between runImpl and pack transitions.
+    // Keyed by requestId; cleared after successful pack.
+    solutionOutputs = new Map();
+    // Transient storage for trajectory collectors produced in runImpl.
+    // emitTrajectory is deferred to pack() so that artifact spans can be added
+    // before the trajectory is finalised and uploaded (Task 16 bidirectional linkage).
+    // Keyed by requestId; cleared after successful pack.
+    // Protected (not private) to allow test subclasses to inject collectors.
+    trajectoryCollectors = new Map();
+    // Transient storage for trajectory CID+sha256 refs produced by runImpl.
+    // Keyed by requestId; cleared after successful pack.
+    trajectoryRefs = new Map();
+    runtimePluginsByRequest = new Map();
+    /** Set by stop(); causes runTickLoop to exit at the next iteration. */
+    stopped = false;
+    constructor(opts) {
+        this.persistence = new TaskRunPersistence(opts.store.db);
+        this.store = opts.store;
+        this.paths = opts.paths;
+        this.claimDeps = opts.claimDeps;
+        this.packagingDeps = opts.packagingDeps;
+        this.envelopeDeps = opts.envelopeDeps;
+        this.deliveryDeps = opts.deliveryDeps;
+        this.implRegistry = opts.implRegistry;
+        this.solverNetRegistry = opts.solverNetRegistry;
+        this.identityPublisher = opts.identityPublisher;
+        this.reputationFeedback = opts.reputationFeedback;
+        this.operatorConfig = opts.operatorConfig;
+    }
+    // ── Public API ──────────────────────────────────────────────────────────────
+    /**
+     * Called when an task is observed from an on-chain event.
+     * Persists a DISCOVERED row. Idempotent: if the row already exists, no-op.
+     */
+    async observe(input) {
+        const existing = this.persistence.getByRequestId(input.requestId);
+        if (!existing) {
+            this.persistence.insertDiscovered(input);
+            console.log(`[harness-engine] observed task ${input.requestId} solverType=${input.solverType ?? 'null'}`);
+        }
+    }
+    /**
+     * Recover all in-flight tasks from persisted state.
+     * Called at daemon startup before beginning normal event processing.
+     * Returns a per-task report for each task attempted.
+     */
+    async recoverInFlight() {
+        const inflight = this.persistence.getInFlight();
+        const results = await Promise.allSettled(inflight.map((task) => this._recoverOne(task)));
+        const reports = results.map((result, i) => {
+            const requestId = inflight[i].requestId;
+            if (result.status === 'fulfilled') {
+                return { requestId, outcome: 'ok' };
+            }
+            else {
+                const error = result.reason instanceof Error
+                    ? result.reason.message
+                    : String(result.reason);
+                return { requestId, outcome: 'failed', error };
+            }
+        });
+        const okCount = reports.filter((r) => r.outcome === 'ok').length;
+        console.log(`[harness-engine] recovery: ${okCount}/${reports.length} tasks resumed`);
+        return reports;
+    }
+    /**
+     * Periodic tick: advance every in-flight task by one transition.
+     * Called by `runTickLoop` so that tasks which entered a non-event-driven
+     * state (e.g. CLAIMED waiting for windowStartTs) get re-driven without
+     * waiting for a daemon restart or a fresh marketplace event.
+     *
+     * Errors from individual tasks are logged but do not stop the loop.
+     */
+    async tick() {
+        const inflight = this.persistence.getInFlight();
+        const results = await Promise.allSettled(inflight.map((task) => this.process(task.requestId)));
+        for (let i = 0; i < results.length; i++) {
+            const r = results[i];
+            if (r.status === 'rejected') {
+                const requestId = inflight[i].requestId;
+                const reason = r.reason instanceof Error ? r.reason.message : String(r.reason);
+                console.warn(`[harness-engine] tick: process(${requestId}) failed: ${reason}`);
+            }
+        }
+    }
+    /**
+     * Drive `tick()` on a fixed interval until `stop()` is called.
+     * Errors thrown by tick() itself are logged and do not stop the loop.
+     */
+    async runTickLoop(intervalMs) {
+        while (!this.stopped) {
+            try {
+                await this.tick();
+            }
+            catch (err) {
+                console.error('[harness-engine] tick loop error (continuing):', err instanceof Error ? err.message : err);
+            }
+            if (this.stopped)
+                break;
+            await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        }
+    }
+    /** Signal `runTickLoop` to exit at the next iteration. */
+    stop() {
+        this.stopped = true;
+    }
+    /**
+     * Process a single task: dispatch by current state to the appropriate
+     * transition. Drives one state transition per call.
+     *
+     * Called both by recovery and by the ongoing event-processing loop.
+     */
+    async process(requestId) {
+        const task = this.persistence.getByRequestId(requestId);
+        if (!task) {
+            throw new Error(`process: task not found: ${requestId}`);
+        }
+        switch (task.state) {
+            case TaskRunState.DISCOVERED:
+                await this._runTransition(task, () => this.claim(task));
+                break;
+            case TaskRunState.CLAIMED: {
+                // Advance to WAITING — persist-before-invoke principle.
+                const oldState = task.state;
+                this.persistence.transition(task.requestId, TaskRunState.WAITING);
+                console.log(`[harness-engine] ${requestId} ${oldState} → ${TaskRunState.WAITING}`);
+                break;
+            }
+            case TaskRunState.WAITING: {
+                const advance = this.dataDrivenAdvance(task);
+                if (advance !== null) {
+                    this.persistence.transition(task.requestId, advance);
+                    console.log(`[harness-engine] ${requestId} ${task.state} → ${advance}`);
+                    await this._runTransition(this.persistence.getOrThrow(requestId), () => this.takePreSnapshot(this.persistence.getOrThrow(requestId)));
+                    // takePreSnapshot transitions PRE_SNAPSHOT → RUNNING. Re-dispatch on
+                    // the post-transition state so RUNNING fires in the same pass (jinn-mono-sae).
+                    const after = this.persistence.getByRequestId(task.requestId);
+                    if (after && after.state === TaskRunState.RUNNING) {
+                        await this.process(task.requestId);
+                    }
+                }
+                // else: not yet time — caller is responsible for scheduling retry
+                break;
+            }
+            case TaskRunState.PRE_SNAPSHOT: {
+                const advance = this.dataDrivenAdvance(task);
+                if (advance !== null) {
+                    // Snapshot already captured (e.g. recovered from crash mid-transition)
+                    this.persistence.transition(task.requestId, advance);
+                    console.log(`[harness-engine] ${requestId} ${task.state} → ${advance}`);
+                    await this._runTransition(this.persistence.getOrThrow(requestId), () => this.runImpl(this.persistence.getOrThrow(requestId)));
+                }
+                else {
+                    await this._runTransition(task, () => this.takePreSnapshot(task));
+                    // takePreSnapshot transitions PRE_SNAPSHOT → RUNNING internally.
+                    // Re-dispatch on the post-transition state so the RUNNING case fires
+                    // in the same pass (jinn-mono-sae fix). Without this, tasks stall
+                    // at RUNNING until the next tick/restart and runImpl never executes.
+                    const after = this.persistence.getByRequestId(task.requestId);
+                    if (after && after.state === TaskRunState.RUNNING) {
+                        await this.process(task.requestId);
+                    }
+                }
+                break;
+            }
+            case TaskRunState.RUNNING:
+                await this._runTransition(task, () => this.runImpl(task));
+                break;
+            case TaskRunState.POST_SNAPSHOT: {
+                const advance = this.dataDrivenAdvance(task);
+                if (advance !== null) {
+                    this.persistence.transition(task.requestId, advance);
+                    console.log(`[harness-engine] ${requestId} ${task.state} → ${advance}`);
+                    await this._runTransition(this.persistence.getOrThrow(requestId), () => this.pack(this.persistence.getOrThrow(requestId)));
+                }
+                else {
+                    await this._runTransition(task, () => this.takePostSnapshot(task));
+                }
+                break;
+            }
+            case TaskRunState.PACKAGING:
+                await this._runTransition(task, () => this.pack(task));
+                break;
+            case TaskRunState.DELIVERING:
+                await this._runTransition(task, () => this.deliver(task));
+                break;
+            case TaskRunState.COMPLETE:
+            case TaskRunState.FAILED:
+                // Terminal — nothing to do.
+                break;
+        }
+    }
+    // ── Transition stubs ────────────────────────────────────────────────────────
+    // Stubs throw NotImplementedError. claim() is implemented here; others are
+    // filled in by subsequent tasks.
+    /**
+     * Two-layer claim: ClaimRegistry + Marketplace.
+     *
+     * Idempotent on resume: checks ClaimRegistry for a pre-existing claim before
+     * sending any on-chain transaction.
+     *
+     * Advances state DISCOVERED → CLAIMED on success.
+     * Marks FAILED if either layer cannot be claimed.
+     *
+     * Requires claimDeps to be injected via constructor options. Falls back to
+     * NotImplementedError if claimDeps is absent (development / test mode).
+     */
+    async claim(task) {
+        if (!this.claimDeps) {
+            throw new NotImplementedError('claim');
+        }
+        // ── Pre-claim impl gate ─────────────────────────────────────────────────
+        // Refuse to claim tasks whose impl is either unregistered (operator has
+        // opted out via config.harnesses.disabled[]) or not ready (external deps
+        // missing — e.g. HL api-wallet not approved for portfolio.v0). Marking
+        // FAILED is terminal so we don't re-attempt; another operator can still
+        // claim from the marketplace.
+        //
+        // Only fires when an implRegistry is wired in (production); tests that
+        // inject claimDeps without a registry intentionally exercise the raw
+        // claim path and are not gated.
+        const solverNet = this.solverNetRegistry && task.solverType
+            ? this.solverNetRegistry.forSolverType(task.solverType)
+            : undefined;
+        if (this.solverNetRegistry && task.solverType && !solverNet) {
+            const reason = `no enabled SolverNet for solverType '${task.solverType}'; run \`jinn solver-nets enable <name>\``;
+            this.persistence.markFailed(task.requestId, reason);
+            console.log(`[harness-engine] ${task.requestId}: skipping claim — ${reason}`);
+            throw new Error(reason);
+        }
+        if (this.implRegistry && task.solverType) {
+            if (!solverNet) {
+                // Unit tests can wire only implRegistry to exercise the Harness gate.
+            }
+            const impl = this.implRegistry.findFor({
+                solverType: task.solverType,
+                role: task.taskRole ?? 'restoration',
+            });
+            if (!impl) {
+                const setHarnessHint = solverNet
+                    ? `jinn solver-nets set-harness ${solverNet.name} <harness>`
+                    : 'jinn solver-nets set-harness <name> <harness>';
+                const reason = `no Harness registered or enabled for solverType '${task.solverType}'; run \`${setHarnessHint}\``;
+                this.persistence.markFailed(task.requestId, reason);
+                console.log(`[harness-engine] ${task.requestId}: skipping claim — ${reason}`);
+                throw new Error(reason);
+            }
+            if (impl.isReady) {
+                const status = await impl.isReady({
+                    solverType: task.solverType,
+                    role: task.taskRole ?? 'restoration',
+                });
+                if (!status.ready) {
+                    const reason = `impl '${impl.name}' not ready: ${status.reason ?? 'unknown'}${status.nextStep?.cli ? ` — run \`${status.nextStep.cli}\`` : ''}`;
+                    this.persistence.markFailed(task.requestId, reason);
+                    console.log(`[harness-engine] ${task.requestId}: skipping claim — ${reason}`);
+                    throw new Error(reason);
+                }
+            }
+        }
+        const { registryClient, marketplaceClaimer } = this.claimDeps;
+        await executeTwoLayerClaim({
+            requestId: task.requestId,
+            windowStartTs: task.windowStartTs,
+        }, registryClient, marketplaceClaimer);
+        // Both layers succeeded. The event path and tick loop can race on the same
+        // DISCOVERED row; if another caller already advanced it, treat this claim as
+        // idempotent and do not rewind or fail the task.
+        const current = this.persistence.getByRequestId(task.requestId);
+        if (!current) {
+            throw new Error(`claim: task not found after claim: ${task.requestId}`);
+        }
+        if (current.state === TaskRunState.DISCOVERED) {
+            this.persistence.transition(task.requestId, TaskRunState.CLAIMED);
+        }
+        else {
+            console.log(`[harness-engine] ${task.requestId}: claim completed but state is already ${current.state}; skipping CLAIMED transition`);
+        }
+    }
+    /**
+     * Release ClaimRegistry claims for all CLAIMED tasks whose work window has
+     * not yet started. Called on graceful engine shutdown.
+     *
+     * Returns the list of requestIds that were successfully released.
+     */
+    async releaseClaimedNotStarted() {
+        if (!this.claimDeps) {
+            return []; // No registry client — nothing to release
+        }
+        const claimed = this.persistence.getByState(TaskRunState.CLAIMED);
+        const released = [];
+        for (const task of claimed) {
+            if (Date.now() < task.windowStartTs) {
+                try {
+                    const ok = await releaseClaimedNotStarted({
+                        requestId: task.requestId,
+                        windowStartTs: task.windowStartTs,
+                    }, this.claimDeps.registryClient);
+                    if (ok) {
+                        released.push(task.requestId);
+                    }
+                }
+                catch (err) {
+                    const reason = err instanceof Error ? err.message : String(err);
+                    console.error(`[harness-engine] releaseClaimedNotStarted failed for ${task.requestId}: ${reason}`);
+                }
+            }
+        }
+        if (released.length > 0) {
+            console.log(`[harness-engine] released ${released.length} pre-window claim(s) on shutdown: ${released.join(', ')}`);
+        }
+        return released;
+    }
+    /**
+     * PRE_SNAPSHOT transition: provision workingDir + implStateDir, write
+     * task.json + env/ files, create sessions/ directory.
+     *
+     * Requires no external deps beyond filesystem access — always implemented.
+     * Advances state PRE_SNAPSHOT with workingDir + implStateDir patch.
+     */
+    async takePreSnapshot(run) {
+        const workingDir = join(this.paths.workingDirRoot, run.requestId);
+        // Resolve the impl via registry so implStateDir matches the path runImpl uses
+        // (join(implStateDirRoot, impl.name, solverType)). Falls back to solverType then 'default'
+        // when no impl is registered — legacy path preserved for health-check tasks.
+        const resolvedImpl = run.solverType
+            ? this.implRegistry?.findFor({ solverType: run.solverType, role: run.taskRole ?? 'restoration' }) ?? null
+            : null;
+        const implStateName = run.implName ?? resolvedImpl?.name ?? run.solverType ?? 'default';
+        const kindSeg = (run.solverType ?? '').replace(/[.:]/g, '_');
+        const implStateDir = kindSeg
+            ? join(this.paths.implStateDirRoot, implStateName, kindSeg)
+            : join(this.paths.implStateDirRoot, implStateName);
+        // Prefer the persisted full Task; fall back to a stub for legacy
+        // (pre-migration) rows so the engine still works for health-check tasks.
+        const task = run.task ?? {
+            id: run.requestId,
+            description: '',
+            ...(run.solverType ? { solverType: run.solverType, spec: {} } : {}),
+            role: run.taskRole ?? 'restoration',
+            window: { startTs: run.windowStartTs, endTs: run.windowEndTs },
+        };
+        provisionWorkingDir(workingDir, task);
+        provisionImplStateDir(implStateDir);
+        // takePreSnapshot transitions directly to RUNNING with the snapshot payload
+        // and workingDir/implStateDir paths set.  We cannot transition
+        // PRE_SNAPSHOT → PRE_SNAPSHOT (invalid); the snapshot is immediately ready
+        // (it's just the provisioned dir context), so we advance to RUNNING in one
+        // step.  The impl is responsible for capturing real market data.
+        this.persistence.transition(run.requestId, TaskRunState.RUNNING, {
+            workingDir,
+            implStateDir,
+            preSnapshotCapturedAt: Date.now(),
+            preSnapshotPayload: { provisioned: true, workingDir },
+        });
+        console.log(`[harness-engine] ${run.requestId} PRE_SNAPSHOT -> RUNNING: workingDir=${workingDir}`);
+    }
+    /**
+     * RUNNING transition: dispatch to a Harness if implRegistry is provided.
+     *
+     * When no impl is found for the solverType, falls back to NotImplementedError
+     * so the engine does not silently swallow the request. In tests that don't
+     * exercise the impl path, override this method.
+     *
+     * Captures impl output in `solutionOutputs` map for pack() to consume. Also
+     * records a minimal post-snapshot so data-driven advance can fire.
+     */
+    async runImpl(task) {
+        const solverType = task.solverType ?? '';
+        const role = task.taskRole ?? 'restoration';
+        const solverNet = solverType ? this.solverNetRegistry?.forSolverType(solverType) : undefined;
+        const impl = this.implRegistry?.findFor({ solverType, role });
+        if (!impl) {
+            throw new NotImplementedError('runImpl');
+        }
+        const runtimePlugins = solverNet
+            ? [solverNet.canonicalPlugin, ...solverNet.plugins]
+            : [];
+        this.runtimePluginsByRequest.set(task.requestId, runtimePlugins);
+        const workingDir = task.workingDir ?? join(this.paths.workingDirRoot, task.requestId);
+        const kindSeg = solverType.replace(/[.:]/g, '_');
+        const implStateDir = task.implStateDir ?? (kindSeg
+            ? join(this.paths.implStateDirRoot, impl.name, kindSeg)
+            : join(this.paths.implStateDirRoot, impl.name));
+        const windowEndTs = task.windowEndTs;
+        const abort = new AbortController();
+        const msUntilEndTs = () => Math.max(0, windowEndTs - Date.now());
+        const endTimer = setTimeout(() => abort.abort(), msUntilEndTs());
+        // Create a trajectory collector for this run.
+        const trajectory = new TrajectoryCollector({
+            taskCid: task.taskCid ?? '',
+            runId: randomUUID(),
+        });
+        try {
+            const ctx = {
+                task: (task.task ?? {
+                    id: task.requestId,
+                    description: '',
+                    ...(task.solverType ? { solverType: task.solverType, spec: {} } : {}),
+                    role,
+                    window: { startTs: task.windowStartTs, endTs: task.windowEndTs },
+                }),
+                taskCid: task.taskCid,
+                solverNet: solverNet ? { name: solverNet.name, solverType: solverNet.solverType } : undefined,
+                runtimePlugins,
+                solverPluginRoots: runtimePlugins.map((plugin) => plugin.root),
+                implStateDir,
+                workingDir,
+                log: (event) => {
+                    console.log(`[harness-impl:${impl.name}] [${event.level}] ${event.msg}`, event.data ?? '');
+                },
+                abort: abort.signal,
+                msUntilEndTs,
+                trajectory,
+            };
+            let output;
+            try {
+                output = await impl.run(ctx);
+            }
+            catch (err) {
+                if (err instanceof SkippableError) {
+                    const skippedAt = Date.now();
+                    const detail = err.message;
+                    console.warn(`[harness-engine] ${task.requestId}: impl=${impl.name} skipped (${err.reason}): ${detail}`);
+                    output = {
+                        venueRef: { name: 'legacy' },
+                        gating: {
+                            skipped: true,
+                            reason: err.reason,
+                            skippedAt: String(skippedAt),
+                        },
+                        informational: {
+                            status: 'skipped',
+                            detail,
+                        },
+                        artifacts: [],
+                    };
+                }
+                else {
+                    throw err;
+                }
+            }
+            this.solutionOutputs.set(task.requestId, output);
+            // Store the trajectory collector so pack() can:
+            //   1. pass it to uploadArtifacts (artifact.emit spans + producedBy metadata)
+            //   2. call emitTrajectory AFTER artifact upload so spans are included
+            //   3. backfill trajectoryCid on artifacts before envelope assembly
+            // emitTrajectory is intentionally deferred to pack() (Task 16).
+            this.trajectoryCollectors.set(task.requestId, trajectory);
+            // Persist impl output BEFORE the state transition so that a crash after
+            // the transition (RUNNING → POST_SNAPSHOT) but before pack() runs will
+            // find the serialised output in the DB on restart. pack() will hydrate the
+            // in-memory map from solutionOutputsJson if the map entry is absent (#6).
+            // Capture post-snapshot from impl output so data-driven advance fires
+            this.persistence.transition(task.requestId, TaskRunState.POST_SNAPSHOT, {
+                postSnapshotCapturedAt: Date.now(),
+                postSnapshotPayload: output.postSnapshot ?? { capturedAt: Date.now(), hlTime: 0, payload: null },
+                fillsPayload: output.fills ?? [],
+                gatingClaim: output.gating,
+                informationalClaim: output.informational ?? null,
+                solutionOutputsJson: JSON.stringify(output),
+                implName: impl.name,
+                runtimePluginsJson: JSON.stringify(runtimePlugins),
+            });
+        }
+        finally {
+            clearTimeout(endTimer);
+        }
+        console.log(`[harness-engine] ${task.requestId} RUNNING → POST_SNAPSHOT via impl=${impl.name}`);
+    }
+    async takePostSnapshot(_intent) {
+        throw new NotImplementedError('takePostSnapshot');
+    }
+    /**
+     * PACKAGING transition: walk workingDir, upload artifacts, assemble + sign
+     * envelope, upload envelope, persist envelope CID + artifact CIDs.
+     *
+     * Requires packagingDeps + envelopeDeps. When absent, falls back to
+     * NotImplementedError.
+     */
+    async pack(task) {
+        // Hydrate implOutput from DB if the in-memory map was lost (e.g. process restart
+        // after RUNNING → POST_SNAPSHOT but before pack() completed). This must run
+        // BEFORE the packagingDeps guard so subclass overrides that call super.pack()
+        // can still benefit from hydration even when packagingDeps is absent (#6).
+        if (!this.solutionOutputs.has(task.requestId) && task.solutionOutputsJson != null) {
+            try {
+                const recovered = JSON.parse(task.solutionOutputsJson);
+                this.solutionOutputs.set(task.requestId, recovered);
+                console.log(`[harness-engine] ${task.requestId}: hydrated solutionOutputs from DB (crash recovery)`);
+            }
+            catch (err) {
+                console.warn(`[harness-engine] ${task.requestId}: failed to hydrate solutionOutputsJson: ${err instanceof Error ? err.message : err}`);
+            }
+        }
+        if (!this.packagingDeps || !this.envelopeDeps) {
+            throw new NotImplementedError('pack');
+        }
+        const workingDir = task.workingDir ?? join(this.paths.workingDirRoot, task.requestId);
+        const implOutput = this.solutionOutputs.get(task.requestId);
+        const implArtifacts = implOutput?.artifacts ?? [];
+        // 1. Walk + upload artifacts (NO registration yet — manifest CID not known).
+        // Pass the trajectory collector (if present) so uploadArtifacts can emit
+        // jinn.artifact.emit spans and attach producedBy back-refs (Task 16 forward
+        // linkage). emitTrajectory is called AFTER upload so artifact spans are included.
+        const collector = this.trajectoryCollectors.get(task.requestId);
+        const packagingDepsWithReq = {
+            ...this.packagingDeps,
+            requestId: task.requestId,
+            ...(collector ? { collector } : {}),
+        };
+        const rawArtifacts = await walkArtifacts(workingDir, implArtifacts);
+        const uploadedArtifacts = await uploadArtifacts(rawArtifacts, packagingDepsWithReq);
+        // 1b. Emit trajectory to IPFS now that all artifact spans have been added.
+        // Non-fatal — envelope assembly continues with envelope.trajectory = null if upload fails.
+        let trajectoryRef = this.trajectoryRefs.get(task.requestId) ?? null;
+        if (!trajectoryRef && collector && this.envelopeDeps) {
+            try {
+                const { privateKeyToAccount } = await import('viem/accounts');
+                const account = privateKeyToAccount(this.envelopeDeps.agentEoaPrivateKey);
+                const { cid, sha256 } = await emitTrajectory({
+                    collector,
+                    runId: collector.runId,
+                    signerPrivateKey: this.envelopeDeps.agentEoaPrivateKey,
+                    signerAddress: account.address,
+                    ipfsRegistryUrl: this.envelopeDeps.ipfsRegistryUrl,
+                });
+                trajectoryRef = { cid, sha256 };
+                console.log(`[harness-engine] ${task.requestId}: trajectory emitted cid=${cid}`);
+            }
+            catch (err) {
+                console.warn(`[harness-engine] ${task.requestId}: trajectory emit failed (non-fatal):`, err instanceof Error ? err.message : err);
+            }
+        }
+        this.trajectoryRefs.set(task.requestId, trajectoryRef);
+        // 1c. Backward linkage: backfill trajectoryCid on all artifacts that have a
+        // producedBy back-ref. This must happen BEFORE assembleAndSignEnvelope so the
+        // signed envelope carries the complete reference (Task 16).
+        if (trajectoryRef) {
+            const trajectoryCid = trajectoryRef.cid;
+            for (const art of uploadedArtifacts) {
+                const pb = art.metadata?.['producedBy'];
+                if (pb != null && typeof pb === 'object' && 'spanId' in pb) {
+                    pb['trajectoryCid'] = trajectoryCid;
+                }
+            }
+        }
+        // Map to Artifact shape (strip localPath)
+        const artifacts = uploadedArtifacts.map(({ localPath: _localPath, ...art }) => art);
+        // 2. Derive agentEoa from private key
+        const { privateKeyToAccount } = await import('viem/accounts');
+        const account = privateKeyToAccount(this.envelopeDeps.agentEoaPrivateKey);
+        const agentEoa = account.address;
+        // Safe multisig address — sourced from envelopeDeps (preferred) or deliveryDeps.
+        // Hard throw if absent: falling back to agentEoa would produce a
+        // protocol-invalid envelope (safeAddress MUST differ from agentEoa, §5.1).
+        const safeAddress = this.envelopeDeps.safeAddress ?? this.deliveryDeps?.safeAddress;
+        if (!safeAddress) {
+            throw new Error('pack: safeAddress not configured in envelopeDeps or deliveryDeps');
+        }
+        // 3. Build envelope payload from impl output (kind-typed, wrapped into payload field)
+        const preSnapshotPayload = task.preSnapshotPayload;
+        const postSnapshotPayload = task.postSnapshotPayload;
+        // The solverType drives payload schema selection. Fall back to 'legacy.v0'
+        // for tasks without a solverType (legacy health-check / daemon-loop-test
+        // tasks that use the legacy-claude impl). The legacy.v0 kind accepts any
+        // Record payload so validatePayload does not reject the output.
+        const solverType = task.solverType ?? 'legacy.v0';
+        // Derive role from Task.role. Evaluator tasks produce 'verdict' envelopes;
+        // all other tasks produce 'restoration' envelopes.
+        const isEvaluation = task.taskRole === 'evaluation';
+        const role = isEvaluation ? 'verdict' : 'restoration';
+        let envelopePayload;
+        if (isEvaluation) {
+            // ── Verdict envelope payload ──────────────────────────────────────────────
+            // The evaluator impl populates verdictPayload on Solution with a
+            // PortfolioV0VerdictPayload-shaped object. Engine passes it through to the
+            // envelope assembler, which runs validatePayload('portfolio.v0', 'verdict', ...).
+            //
+            // If verdictPayload is absent (impl bug / crash recovery), fall back to a
+            // minimal INDETERMINATE stub so the envelope assembly does not silently succeed
+            // with a wrong shape — validatePayload will catch schema mismatches.
+            //
+            // verificationOfRestoration: stubbed — Plan D will connect the real SDK.
+            // restorationEnvelope.sha256: placeholder — Plan D wires real sha256 derivation.
+            const verdictPayload = implOutput?.verdictPayload;
+            if (!verdictPayload) {
+                throw new Error(`pack: evaluator impl for ${task.requestId} did not produce verdictPayload on Solution; ` +
+                    `ensure the impl populates output.verdictPayload`);
+            }
+            // If the (stub) verificationOfRestoration reports 'invalid', downgrade verdict
+            // to REJECTED per scope §3.3.  For V1 the stub always returns 'valid', so this
+            // path does not fire in practice — Plan D makes it real.
+            const verif = verdictPayload['verificationOfRestoration'];
+            if (verif?.overall === 'invalid') {
+                // Override verdict to REJECTED; preserve the rest of the payload.
+                envelopePayload = {
+                    ...verdictPayload,
+                    verdict: 'REJECTED',
+                };
+            }
+            else {
+                envelopePayload = verdictPayload;
+            }
+        }
+        else if (implOutput?.solutionPayload) {
+            // ── Non-portfolio restoration envelope payload ────────────────────────────
+            // Impls for kinds with a non-portfolio payload schema (e.g. prediction.v0)
+            // declare their own fully-formed payload. Engine passes it through directly
+            // so validatePayload() can check it against the per-kind schema.
+            envelopePayload = implOutput.solutionPayload;
+        }
+        else {
+            // ── Portfolio restoration envelope payload (legacy / portfolio.v0) ─────────
+            envelopePayload = {
+                preSnapshot: {
+                    capturedAt: task.preSnapshotCapturedAt ?? Date.now(),
+                    hlTime: preSnapshotPayload?.hlTime ?? 0,
+                    // Double-fallback: first tries the structured .payload field (normal shape),
+                    // then falls back to the whole payload object (handles takePreSnapshot's
+                    // synthetic shape where the snapshot IS the top-level object, not nested).
+                    payload: preSnapshotPayload?.payload ?? preSnapshotPayload ?? {},
+                },
+                postSnapshot: {
+                    capturedAt: task.postSnapshotCapturedAt ?? Date.now(),
+                    hlTime: postSnapshotPayload?.hlTime ?? 0,
+                    // Same double-fallback as above.
+                    payload: postSnapshotPayload?.payload ?? postSnapshotPayload ?? {},
+                },
+                fills: task.fillsPayload ?? [],
+                gating: task.gatingClaim ?? {},
+                ...(task.informationalClaim != null
+                    ? { informational: task.informationalClaim }
+                    : {}),
+                ...(implOutput?.rationale != null ? { rationale: implOutput.rationale } : {}),
+            };
+        }
+        // 4. Persist generatedAt once (first pack); reuse on retry for CID determinism.
+        const generatedAt = task.manifestGeneratedAt ?? Date.now();
+        if (!task.manifestGeneratedAt) {
+            // Persist before assembling so that a crash after assembly but before
+            // transition still gets the same generatedAt on the next attempt.
+            this.persistence.setManifestGeneratedAt(task.requestId, generatedAt);
+        }
+        // 5. Assemble + sign envelope → envelope CID now known.
+        // trajectoryRef was computed in step 1b above (emitted after artifact upload).
+        // Per the post-gating-fix schema, trajectory references carry sha256 + access
+        // (the operator HTTP endpoint that serves the bytes). Phase 3 (jinn-mono-vy37.1.3)
+        // sources this from the engine's operatorConfig; absent operatorConfig (e.g. test
+        // fixtures) falls back to packagingDeps.operatorEndpoint, then to a localhost
+        // sentinel so suites that don't exercise the publish path still pack cleanly.
+        const operatorEndpointForTraj = this.operatorConfig?.publicEndpoint
+            ?? this.packagingDeps?.operatorEndpoint
+            ?? 'http://localhost:7331';
+        const envelopeTrajectory = trajectoryRef
+            ? {
+                sha256: trajectoryRef.sha256,
+                access: { endpoint: operatorEndpointForTraj, priceUsdc: '0' },
+            }
+            : null;
+        // evidenceTier reflects the on-chain commitment state at the time of signing.
+        // For the V2 claim flow, claimDelivery will write an evidenceHash on-chain,
+        // so the envelope should be declared 'committed'. For V1 or unknown flows,
+        // 'self-signed' is accurate (no on-chain hash commitment).
+        const evidenceTier = this.deliveryDeps?.claimDeliveryVariant === 'v2' ? 'committed' : 'self-signed';
+        const runtimePlugins = this.runtimePluginsByRequest.get(task.requestId)
+            ?? (task.runtimePluginsJson ? JSON.parse(task.runtimePluginsJson) : []);
+        const executorPlugins = runtimePlugins
+            .map((plugin) => ({
+            name: plugin.name,
+            version: plugin.version,
+            ...(plugin.cid ? { cid: plugin.cid } : {}),
+            sha256: plugin.sha256,
+        }))
+            .sort((a, b) => `${a.name}@${a.version}`.localeCompare(`${b.name}@${b.version}`));
+        const implNameForEnvelope = task.implName ?? solverType;
+        const solverNet = solverType ? this.solverNetRegistry?.forSolverType(solverType) : undefined;
+        const runtimeBundleDigest = `sha256:${createHash('sha256')
+            .update(JSON.stringify({
+            harness: {
+                name: implNameForEnvelope,
+                version: buildInfo.implVersion,
+                codeDigest: buildInfo.codeDigest,
+            },
+            solverNet: solverNet ? { name: solverNet.name, solverType: solverNet.solverType } : null,
+            plugins: executorPlugins,
+        }))
+            .digest('hex')}`;
+        const envelopeInputs = {
+            solverType,
+            role,
+            task: {
+                cid: task.taskCid,
+                onchainCreationTx: task.onchainCreationTx,
+                onchainCreationBlock: task.onchainCreationBlock,
+                requestId: task.requestId,
+            },
+            participant: { safeAddress, agentEoa },
+            window: { startTs: task.windowStartTs, endTs: task.windowEndTs },
+            executor: {
+                implName: implNameForEnvelope,
+                // buildInfo resolves to real values in production builds; falls back to
+                // clearly-labelled placeholders ('dev' / 'sha256:dev-build') when running
+                // via tsx without a prior `yarn build` (dev mode).
+                implVersion: buildInfo.implVersion,
+                clientGitSha: buildInfo.clientGitSha,
+                codeDigest: buildInfo.codeDigest,
+                runtimeBundleDigest,
+                plugins: executorPlugins,
+                signingKey: { kind: 'agent-eoa', pubkey: agentEoa },
+            },
+            evidenceTier,
+            trajectory: envelopeTrajectory,
+            artifacts,
+            payload: envelopePayload,
+            generatedAt,
+        };
+        const { envelopeCid, envelopeHash } = await assembleAndSignEnvelope(envelopeInputs, this.envelopeDeps);
+        const manifestCid = envelopeCid;
+        const signatureHash = envelopeHash;
+        // 6. ERC-8004 IdentityRegistry per-execution `setMetadata` fires in
+        //    deliver() AFTER claimDelivery succeeds. 'committed' must mean
+        //    "observable on-chain evidenceHash exists" — publishing before claim
+        //    would lie during failures. The evidenceHash (signatureHash) is
+        //    persisted to DELIVERING state below and reused by deliver().
+        //    Operator-rooted entity model: docs/superpowers/specs/2026-04-27-erc-8004-entity-model-design.md.
+        // 7. Build artifact sha256 map for persistence.
+        // Post-gating-fix (spec §1): artifacts no longer have IPFS CIDs — bytes
+        // live in served_artifacts keyed by sha256. We reuse the legacy
+        // `artifactCids` persistence column (key: localPath) but populate it with
+        // sha256 hashes so downstream readers still get a stable identifier.
+        const artifactCids = {};
+        for (const art of uploadedArtifacts) {
+            artifactCids[art.localPath] = art.sha256;
+        }
+        // Backfill envelope_cid (manifestCid) on every served_artifacts row so
+        // the operator can answer manifest-rooted lookups later. Done after the
+        // manifest CID is known.
+        for (const art of uploadedArtifacts) {
+            this.store.setServedArtifactEnvelopeCid(art.sha256, manifestCid);
+        }
+        // 8. Persist DELIVERING with manifest CID + artifact CIDs + evidence hash.
+        //    evidenceHash gets its own dedicated column (not stashed in informationalClaim).
+        this.persistence.transition(task.requestId, TaskRunState.DELIVERING, {
+            manifestCid,
+            artifactCids,
+            evidenceHash: signatureHash,
+        });
+        console.log(`[harness-engine] ${task.requestId} PACKAGING → DELIVERING manifestCid=${manifestCid}`);
+        // Clean up transient state (no longer needed after DELIVERING)
+        this.solutionOutputs.delete(task.requestId);
+        this.trajectoryCollectors.delete(task.requestId);
+        this.trajectoryRefs.delete(task.requestId);
+    }
+    /**
+     * DELIVERING transition: call mech.deliverToMarketplace + JinnRouter.claimDelivery.
+     *
+     * Requires deliveryDeps. When absent, falls back to NotImplementedError.
+     *
+     * Crash-recovery safe: if `task.deliveryTxHash` is already set (persisted
+     * after a previous deliverToMarketplace call that completed before the process
+     * crashed), we skip the deliver step and go straight to claimDelivery.
+     */
+    async deliver(task) {
+        if (!this.deliveryDeps) {
+            throw new NotImplementedError('deliver');
+        }
+        const manifestCid = task.manifestCid;
+        if (!manifestCid) {
+            throw new Error(`deliver: manifestCid missing for ${task.requestId}`);
+        }
+        // Guard: v2 claimDelivery requires an evidenceHash — a zero fallback would
+        // silently brick staking rewards, so we fail loudly instead.
+        const evidenceHash = task.evidenceHash;
+        if (!evidenceHash && this.deliveryDeps.claimDeliveryVariant === 'v2') {
+            throw new MissingEvidenceHashError(task.requestId);
+        }
+        // Capture locals for use in the onDeliveryTxLanded closure.
+        const requestId = task.requestId;
+        const persistence = this.persistence;
+        const { deliveryTxHash, claimTxHash } = await deliverAndClaim(requestId, manifestCid, evidenceHash, this.deliveryDeps, 
+        // Recovery: pass existing deliveryTxHash so deliverToMarketplace is skipped.
+        task.deliveryTxHash ?? undefined, 
+        // Persist deliveryTxHash before claimDelivery so recovery can resume from here.
+        async (txHash) => {
+            persistence.setDeliveryTxHash(requestId, txHash);
+        });
+        this.persistence.transition(requestId, TaskRunState.COMPLETE, {
+            deliveryTxHash,
+        });
+        console.log(`[harness-engine] ${requestId} DELIVERING → COMPLETE deliveryTx=${deliveryTxHash} claimTx=${claimTxHash}`);
+        // Emit a SQLite artifact row so consumers (release acceptance gate, search
+        // API) see this cycle alongside legacy-claude / MCP-emitted rows. The
+        // legacy claude path writes via the MCP `submit_restoration_result` tool;
+        // deterministic impls (prediction-v0-baseline, prediction-v0-evaluator,
+        // …) don't go through MCP, so the engine emits on their behalf here.
+        // Idempotent: skips when a row for this requestId+tag already exists
+        // (legacy path may have already inserted).
+        this.emitCycleArtifact(task, manifestCid, evidenceHash);
+        // ── ERC-8004 setMetadata — fires AFTER claimDelivery succeeds ────────────
+        //
+        // Moved here from pack() per PR#37 review2 must-fix #2. 'committed' means
+        // "observable on-chain evidenceHash exists" — publishing before claim would
+        // lie during failures. evidenceHash comes from task (persisted in
+        // DELIVERING state by pack()); idempotent on retry (setMetadata is a pure
+        // key-value write; re-running with the same payload is safe).
+        //
+        // Restoration-only for now. Evaluator setMetadata lands with jinn-mono-2ff.
+        if (this.identityPublisher) {
+            const taskRoleRaw = task.taskRole ?? 'restoration';
+            if (taskRoleRaw === 'restoration') {
+                const signatureHash = evidenceHash;
+                // v0 tier rule: with an evidenceHash on chain we declare `committed` (tier=1);
+                // higher tiers (`attested`, `proved`) come later when TEE work lands.
+                const tier = signatureHash ? 1 : 0;
+                const setMetadataPayload = {
+                    version: 1,
+                    tier,
+                    manifestHash: signatureHash ?? '0x',
+                    attestationQuoteCid: '0x',
+                    sourceMeasurement: '0x0000000000000000000000000000000000000000000000000000000000000000',
+                };
+                try {
+                    const pubTxHash = await this.identityPublisher.publishContent({
+                        kind: 'envelope',
+                        cid: manifestCid,
+                        payload: setMetadataPayload,
+                    });
+                    console.log(`[harness-engine] ${requestId}: setMetadata envelope:${manifestCid} tx=${pubTxHash}`);
+                }
+                catch (err) {
+                    console.warn(`[harness-engine] ${requestId}: setMetadata envelope publish failed (non-fatal): ${err instanceof Error ? err.message : err}`);
+                }
+            }
+        }
+        // ── Reputation feedback hook (jinn-mono-yg4) ─────────────────────────────
+        //
+        // Evaluator-only path: after `claimDelivery` settles the verdict, fire
+        // `ReputationRegistry.giveFeedback(harnessAgentId, ...)` so the
+        // harness's agent NFT accrues a rating (DR §4.3).
+        //
+        // Best-effort: any failure inside the hook is logged but does not
+        // change the COMPLETE state. claimDelivery is already authoritative.
+        if (task.taskRole === 'evaluation' && this.reputationFeedback) {
+            await this._maybePostEvaluatorFeedback(task).catch((err) => {
+                console.warn(`[harness-engine] ${requestId}: reputation feedback hook errored unexpectedly (non-fatal): ${err instanceof Error ? err.message : err}`);
+            });
+        }
+    }
+    /**
+     * Post evaluator feedback on the harness's agent NFT.
+     *
+     * Pulls the verdict from the persisted gating claim (the evaluator impl
+     * writes `{ verdict, score, scoreBasis, ... }` into `output.gating`),
+     * resolves the harness's `agentId` via the configured subgraph
+     * resolver, and submits a single `ReputationRegistry.giveFeedback` tx.
+     *
+     * Skipped silently when:
+     *   - No `reputationFeedback` deps wired.
+     *   - `gatingClaim` doesn't carry a verdict (impl shape mismatch — log and
+     *     return).
+     *   - The parent harness's manifest hash isn't reachable from the
+     *     persisted state — log and return).
+     *   - `resolveAgentId` returns null (subgraph not indexed yet, or no
+     *     subgraph URL configured at all — log and return).
+     *
+     * The mapping policy (PASS / FAIL / REJECTED / INDETERMINATE → score) lives
+     * inside `submitEvaluatorFeedback` / `mapVerdictToScore` in the
+     * feedback-hook module; we just hand it the verdict.
+     */
+    /**
+     * Insert a SQLite `artifacts` row for a successfully delivered cycle so the
+     * release acceptance gate (and the search API) can observe completion via
+     * the same surface as the legacy claude / MCP path.
+     *
+     * The legacy `legacy-claude` impl writes via the MCP `submit_restoration_result`
+     * tool when Claude reports success; deterministic impls don't go through MCP.
+     * This emitter closes that gap by writing the row from the engine when the
+     * cycle hits COMPLETE.
+     *
+     * Idempotent: if a row already exists for (requestId, tag) — e.g. the legacy
+     * MCP path got there first — we leave it alone.
+     */
+    emitCycleArtifact(task, manifestCid, evidenceHash) {
+        const taskId = task.task?.id;
+        if (!taskId) {
+            // Rows without task payload cannot be attributed to a Task id. Skip
+            // rather than synthesise provenance.
+            return;
+        }
+        const taskRole = task.taskRole ?? 'restoration';
+        const tag = taskRole === 'evaluation' ? 'evaluation-verdict' : 'restoration-result';
+        const existing = this.store.getArtifactByRequestId(task.requestId, tag);
+        if (existing)
+            return;
+        this.store.insertArtifact({
+            id: randomUUID(),
+            taskId,
+            requestId: task.requestId,
+            title: `${tag}: ${task.solverType ?? 'cycle'} (${task.implName ?? 'engine'})`,
+            content: JSON.stringify({
+                manifestCid,
+                evidenceHash: evidenceHash ?? null,
+                implName: task.implName,
+            }),
+            tags: [tag, 'success'],
+            outcome: 'SUCCESS',
+        });
+    }
+    async _maybePostEvaluatorFeedback(task) {
+        if (!this.reputationFeedback)
+            return;
+        const gating = task.gatingClaim;
+        const verdictRaw = gating?.['verdict'];
+        if (verdictRaw !== 'PASS' &&
+            verdictRaw !== 'FAIL' &&
+            verdictRaw !== 'REJECTED' &&
+            verdictRaw !== 'INDETERMINATE') {
+            console.warn(`[harness-engine] ${task.requestId}: reputation feedback skipped — gatingClaim has no recognised verdict (got=${String(verdictRaw)})`);
+            return;
+        }
+        const verdict = verdictRaw;
+        // Pull the parent harness's manifest evidence from the inlined eval
+        // payload. The evaluator impl receives the harness's signed manifest
+        // JSON via `task.context.restorationResult` (see
+        // `MechAdapter.tryCreateEvaluationJob`). Its `signature.hash` is
+        // exactly what the harness committed via `claimDelivery(evidenceHash)`.
+        const parent = this._extractHarnessManifestRef(task);
+        if (!parent) {
+            console.warn(`[harness-engine] ${task.requestId}: reputation feedback skipped — could not extract harness manifest hash from inlined evaluation payload`);
+            return;
+        }
+        let resolved;
+        try {
+            resolved = await this.reputationFeedback.resolveAgentId(parent.evidenceHash);
+        }
+        catch (err) {
+            console.warn(`[harness-engine] ${task.requestId}: reputation feedback resolver threw (non-fatal): ${err instanceof Error ? err.message : err}`);
+            return;
+        }
+        if (!resolved) {
+            console.log(`[harness-engine] ${task.requestId}: reputation feedback skipped — no agentId resolved for harness manifestHash=${parent.evidenceHash} (subgraph not indexed yet, or no envelope published)`);
+            return;
+        }
+        // CID resolution priority: subgraph row's `manifestCid` (cheapest, the
+        // operator already published an envelope under it), else the inlined
+        // CID hint when present, else fall back to the bare hash. The subgraph
+        // parses `manifest:<cid>` to a `manifestRef` regardless.
+        const manifestCid = resolved.manifestCid ?? parent.manifestCid ?? '';
+        // The SolverType is the same value used by the restoration —
+        // `task.solverType` is "portfolio.v0" both for the restoration and its
+        // evaluation. Tag1 is indexed on the on-chain event, so cheap to filter.
+        const kind = task.solverType ?? undefined;
+        const verdictArg = kind ? { verdict, solverType: kind } : { verdict };
+        let outcome;
+        try {
+            outcome = await submitEvaluatorFeedback({
+                registry: this.reputationFeedback.client,
+                ref: {
+                    harnessAgentId: resolved.agentId,
+                    harnessManifestCid: manifestCid,
+                    harnessEvidenceHash: parent.evidenceHash,
+                },
+                verdict: verdictArg,
+            });
+        }
+        catch (err) {
+            // submitEvaluatorFeedback already swallows known reverts, but a
+            // truly unexpected throw still must not propagate past delivery.
+            console.warn(`[harness-engine] ${task.requestId}: reputation feedback unexpected throw (non-fatal): ${err instanceof Error ? err.message : err}`);
+            return;
+        }
+        console.log(`[harness-engine] ${task.requestId}: reputation feedback ${outcome.kind} verdict=${verdict} harnessAgentId=${resolved.agentId.toString()}`);
+    }
+    /**
+     * Extract the harness's `evidenceHash` (and best-effort `manifestCid`)
+     * from the persisted evaluation task.
+     *
+     * The evaluator's `task.context.restorationResult` holds the harness's
+     * full signed manifest JSON inlined as a string (per
+     * `MechAdapter.tryCreateEvaluationJob`). We parse it and pull the
+     * `signature.hash`, which is exactly the on-chain `evidenceHash`.
+     *
+     * The CID is not always inlined — the manifest carries its own
+     * `task.cid` field (the *original task* CID), not its self-CID. We
+     * therefore return `manifestCid: null` here and rely on the subgraph
+     * resolver to surface the published manifest CID. Returns `null` when
+     * the inlined payload is missing or malformed.
+     */
+    _extractHarnessManifestRef(task) {
+        const ds = task.task;
+        const inlined = ds?.context?.['restorationResult'];
+        if (typeof inlined !== 'string' || inlined.length === 0) {
+            return null;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(inlined);
+        }
+        catch {
+            return null;
+        }
+        if (typeof parsed !== 'object' || parsed === null) {
+            return null;
+        }
+        const sig = parsed['signature'];
+        if (typeof sig !== 'object' || sig === null) {
+            return null;
+        }
+        const hashRaw = sig['hash'];
+        if (typeof hashRaw !== 'string' || !/^0x[0-9a-fA-F]{64}$/.test(hashRaw)) {
+            return null;
+        }
+        return {
+            evidenceHash: hashRaw,
+            manifestCid: null,
+        };
+    }
+    // ── Internal helpers ────────────────────────────────────────────────────────
+    /**
+     * Returns the next state if the current state can be advanced purely from
+     * persisted data (no external work needed), or null if external work is required.
+     *
+     * Used for crash recovery and for collapsing transitions in process()
+     * when a previous run already produced the data.
+     */
+    dataDrivenAdvance(task) {
+        switch (task.state) {
+            case TaskRunState.WAITING:
+                return Date.now() >= task.windowStartTs ? TaskRunState.PRE_SNAPSHOT : null;
+            case TaskRunState.PRE_SNAPSHOT:
+                return task.preSnapshotPayload != null ? TaskRunState.RUNNING : null;
+            case TaskRunState.POST_SNAPSHOT:
+                return task.postSnapshotPayload != null ? TaskRunState.PACKAGING : null;
+            default:
+                return null;
+        }
+    }
+    /**
+     * Wraps a transition method call with error handling: if the transition
+     * throws, the task is marked FAILED with the error message.
+     */
+    async _runTransition(task, fn) {
+        const oldState = task.state;
+        try {
+            await fn();
+            const updated = this.persistence.getByRequestId(task.requestId);
+            if (updated && updated.state !== oldState) {
+                console.log(`[harness-engine] ${task.requestId} ${oldState} → ${updated.state}`);
+            }
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            this.persistence.markFailed(task.requestId, reason);
+            throw err;
+        }
+    }
+    /**
+     * Recovery handler for a single in-flight task.
+     * Dispatches by state per §6.5.
+     */
+    async _recoverOne(task) {
+        try {
+            await this._recoverDispatch(task);
+        }
+        catch (err) {
+            // If recovery itself throws (e.g. NotImplementedError stub), mark failed.
+            // NotImplementedError is expected during development; don't swallow it in prod.
+            const reason = err instanceof Error ? err.message : String(err);
+            // Only mark failed if the task is still in the same non-terminal state
+            // (another concurrent recovery pass might have already advanced it).
+            const current = this.persistence.getByRequestId(task.requestId);
+            if (current && current.state === task.state) {
+                this.persistence.markFailed(task.requestId, `recovery: ${reason}`);
+                console.error(`[harness-engine] resume failed for ${task.requestId}: ${reason}`);
+            }
+            throw err;
+        }
+    }
+    /**
+     * Per-state recovery dispatch per §6.5.
+     */
+    async _recoverDispatch(task) {
+        switch (task.state) {
+            case TaskRunState.DISCOVERED:
+                // Ready to claim — delegate to claim flow (subsequent task).
+                // Stub: leaves state unchanged; logs task is ready.
+                await this.claim(task);
+                break;
+            case TaskRunState.CLAIMED:
+                // Advance to WAITING — no side effect needed.
+                this.persistence.transition(task.requestId, TaskRunState.WAITING);
+                await this._recoverDispatch(this.persistence.getOrThrow(task.requestId));
+                break;
+            case TaskRunState.WAITING: {
+                const advance = this.dataDrivenAdvance(task);
+                if (advance !== null) {
+                    // Window has started — advance immediately.
+                    this.persistence.transition(task.requestId, advance);
+                    await this._recoverDispatch(this.persistence.getOrThrow(task.requestId));
+                }
+                // else: schedule a timer for startTs — caller handles scheduling.
+                break;
+            }
+            case TaskRunState.PRE_SNAPSHOT: {
+                const advance = this.dataDrivenAdvance(task);
+                if (advance !== null) {
+                    // Snapshot already in DB — advance to RUNNING.
+                    this.persistence.transition(task.requestId, advance);
+                    await this._recoverDispatch(this.persistence.getOrThrow(task.requestId));
+                }
+                else {
+                    // Need to (re-)fetch snapshot.
+                    await this.takePreSnapshot(task);
+                    // takePreSnapshot transitions PRE_SNAPSHOT → RUNNING. Re-dispatch
+                    // against the post-transition state so runImpl actually fires for
+                    // tasks that were persisted at CLAIMED/WAITING/PRE_SNAPSHOT
+                    // before a restart (otherwise recovery stops at RUNNING-but-not-run).
+                    const after = this.persistence.getByRequestId(task.requestId);
+                    if (after && after.state !== task.state && after.state !== TaskRunState.FAILED) {
+                        await this._recoverDispatch(after);
+                    }
+                }
+                break;
+            }
+            case TaskRunState.RUNNING:
+                // Re-spawn impl with workingDir + implStateDir intact.
+                await this.runImpl(task);
+                break;
+            case TaskRunState.POST_SNAPSHOT: {
+                const advance = this.dataDrivenAdvance(task);
+                if (advance !== null) {
+                    // Snapshot already in DB — advance to PACKAGING.
+                    this.persistence.transition(task.requestId, advance);
+                    await this._recoverDispatch(this.persistence.getOrThrow(task.requestId));
+                }
+                else {
+                    await this.takePostSnapshot(task);
+                }
+                break;
+            }
+            case TaskRunState.PACKAGING:
+                // Re-walk workingDir + Solution; re-upload missing CIDs.
+                await this.pack(task);
+                break;
+            case TaskRunState.DELIVERING:
+                // Chain query — if already delivered → COMPLETE; else retry.
+                await this.deliver(task);
+                break;
+            case TaskRunState.COMPLETE:
+            case TaskRunState.FAILED:
+                // Terminal — nothing to recover.
+                break;
+        }
+    }
+}
+//# sourceMappingURL=engine.js.map