@riddledc/riddle-proof 0.2.0 → 0.4.0

package/dist/engine-harness.cjs

@@ -0,0 +1,924 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/engine-harness.ts
+var engine_harness_exports = {};
+__export(engine_harness_exports, {
+  createDisabledRiddleProofAgentAdapter: () => createDisabledRiddleProofAgentAdapter,
+  readRiddleProofRunStatus: () => readRiddleProofRunStatus,
+  runRiddleProofEngineHarness: () => runRiddleProofEngineHarness
+});
+module.exports = __toCommonJS(engine_harness_exports);
+var import_node_child_process = require("child_process");
+var import_node_fs = require("fs");
+var import_node_path = __toESM(require("path"), 1);
+var import_node_crypto = __toESM(require("crypto"), 1);
+
+// src/result.ts
+function isSuccessfulStatus(status) {
+  return status !== "blocked" && status !== "failed";
+}
+function compactRecord(input) {
+  return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== void 0 && value !== null && value !== ""));
+}
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function recordValue(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function normalizeTerminalMetadata(input) {
+  const riddleState = recordValue(input.riddleState) || {};
+  const result = recordValue(input.engineResult) || {};
+  const contract = recordValue(result.checkpointContract) || {};
+  const details = recordValue(input.checkpointDetails) || recordValue(contract.details) || {};
+  const markedReady = riddleState.marked_ready ?? result.marked_ready ?? result.markedReady ?? details.marked_ready ?? details.markedReady;
+  const finalized = riddleState.finalized ?? result.finalized ?? details.finalized;
+  return compactRecord({
+    pr_url: nonEmptyString(riddleState.pr_url) || nonEmptyString(result.pr_url) || nonEmptyString(result.prUrl) || nonEmptyString(details.pr_url) || nonEmptyString(details.prUrl),
+    marked_ready: typeof markedReady === "boolean" ? markedReady : void 0,
+    notification: recordValue(riddleState.notification) || recordValue(riddleState.discord_notification) || recordValue(result.notification) || recordValue(result.discord_notification),
+    proof_decision: nonEmptyString(riddleState.proof_decision) || nonEmptyString(result.proof_decision),
+    merge_recommendation: nonEmptyString(riddleState.merge_recommendation) || nonEmptyString(result.merge_recommendation),
+    finalized: typeof finalized === "boolean" ? finalized : void 0
+  });
+}
+function applyTerminalMetadata(state, metadata) {
+  const prUrl = nonEmptyString(metadata.pr_url);
+  if (prUrl) state.pr_url = prUrl;
+  if (typeof metadata.marked_ready === "boolean") state.marked_ready = metadata.marked_ready;
+  const notification = recordValue(metadata.notification);
+  if (notification) state.notification = notification;
+  const proofDecision = nonEmptyString(metadata.proof_decision);
+  if (proofDecision) state.proof_decision = proofDecision;
+  const mergeRecommendation = nonEmptyString(metadata.merge_recommendation);
+  if (mergeRecommendation) state.merge_recommendation = mergeRecommendation;
+  if (typeof metadata.finalized === "boolean") state.finalized = metadata.finalized;
+  return state;
+}
+function createRunResult(input) {
+  const status = input.status || input.state.status;
+  const ok = isSuccessfulStatus(status);
+  const state = input.metadata ? applyTerminalMetadata(input.state, input.metadata) : input.state;
+  state.status = status;
+  state.ok = ok;
+  return compactRecord({
+    ok,
+    status,
+    run_id: state.run_id,
+    state_path: input.state_path ?? state.state_path ?? null,
+    worktree_path: state.worktree_path ?? null,
+    branch: state.branch ?? null,
+    current_stage: state.current_stage ?? null,
+    iterations: state.iterations,
+    last_checkpoint: state.last_checkpoint ?? null,
+    last_summary: input.last_summary ?? null,
+    event_count: state.events.length,
+    pr_url: state.pr_url,
+    marked_ready: state.marked_ready,
+    notification: state.notification,
+    proof_decision: state.proof_decision,
+    merge_recommendation: state.merge_recommendation,
+    finalized: state.finalized,
+    blocker: state.blocker,
+    evidence_bundle: input.evidence_bundle,
+    raw: input.raw
+  });
+}
+
+// src/state.ts
+var RIDDLE_PROOF_RUN_STATE_VERSION = "riddle-proof.run-state.v1";
+function timestamp() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function createRunId(createdAt) {
+  const stamp = createdAt.replace(/\D/g, "").slice(0, 14) || "unknown";
+  const entropy = Math.random().toString(36).slice(2, 8) || "run";
+  return `rp_${stamp}_${entropy}`;
+}
+function elapsedMs(start, end) {
+  const startMs = start ? Date.parse(start) : NaN;
+  const endMs = end ? Date.parse(end) : NaN;
+  if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) return void 0;
+  return Math.max(0, endMs - startMs);
+}
+function normalizeIntegrationContext(input, fallbackSource) {
+  const value = recordValue(input);
+  if (!value) {
+    return fallbackSource ? { source: fallbackSource } : void 0;
+  }
+  const metadata = recordValue(value.metadata);
+  return compactRecord({
+    source: nonEmptyString(value.source) || fallbackSource,
+    channel_id: nonEmptyString(value.channel_id),
+    thread_id: nonEmptyString(value.thread_id),
+    message_id: nonEmptyString(value.message_id),
+    source_url: nonEmptyString(value.source_url),
+    metadata: metadata && Object.keys(metadata).length ? metadata : void 0
+  });
+}
+function normalizeRunParams(input) {
+  return compactRecord({
+    repo: input.repo,
+    branch: input.branch,
+    change_request: input.change_request,
+    commit_message: input.commit_message,
+    prod_url: input.prod_url,
+    capture_script: input.capture_script,
+    success_criteria: input.success_criteria,
+    assertions: input.assertions,
+    verification_mode: input.verification_mode,
+    reference: input.reference,
+    base_branch: input.base_branch,
+    before_ref: input.before_ref,
+    allow_static_preview_fallback: input.allow_static_preview_fallback,
+    context: input.context,
+    reviewer: input.reviewer,
+    mode: input.mode,
+    build_command: input.build_command,
+    build_output: input.build_output,
+    server_image: input.server_image,
+    server_command: input.server_command,
+    server_port: input.server_port,
+    server_path: input.server_path,
+    use_auth: input.use_auth,
+    color_scheme: input.color_scheme,
+    wait_for_selector: input.wait_for_selector,
+    ship_mode: input.ship_mode,
+    engine_state_path: input.engine_state_path,
+    harness_state_path: input.harness_state_path,
+    max_iterations: input.max_iterations,
+    auto_approve: input.auto_approve,
+    dry_run: input.dry_run,
+    integration_context: normalizeIntegrationContext(input.integration_context)
+  });
+}
+function createRunState(input) {
+  const createdAt = input.created_at || timestamp();
+  return compactRecord({
+    version: RIDDLE_PROOF_RUN_STATE_VERSION,
+    run_id: input.run_id || createRunId(createdAt),
+    state_path: input.state_path,
+    worktree_path: input.worktree_path,
+    branch: input.branch || input.request.branch,
+    current_stage: input.current_stage ?? null,
+    stage_started_at: input.stage_started_at ?? null,
+    status: input.status || "running",
+    created_at: createdAt,
+    updated_at: input.updated_at || createdAt,
+    request: normalizeRunParams(input.request),
+    iterations: input.iterations ?? 0,
+    last_checkpoint: input.last_checkpoint ?? null,
+    events: input.events ? [...input.events] : []
+  });
+}
+function appendRunEvent(state, input) {
+  const event = {
+    ts: input.ts || timestamp(),
+    kind: input.kind,
+    checkpoint: input.checkpoint,
+    stage: input.stage,
+    summary: input.summary,
+    details: input.details
+  };
+  state.events.push(compactRecord({
+    ts: event.ts,
+    kind: event.kind,
+    checkpoint: event.checkpoint,
+    stage: event.stage,
+    summary: event.summary,
+    details: event.details
+  }));
+  if (input.checkpoint !== void 0) state.last_checkpoint = input.checkpoint;
+  if (input.stage !== void 0) {
+    if (state.current_stage !== input.stage) state.stage_started_at = event.ts;
+    state.current_stage = input.stage;
+  }
+  state.updated_at = event.ts;
+  return state;
+}
+function appendStageHeartbeat(state, input) {
+  const at = input.ts || timestamp();
+  return appendRunEvent(state, {
+    ts: at,
+    kind: "stage.heartbeat",
+    checkpoint: input.checkpoint || `${input.stage}_heartbeat`,
+    stage: input.stage,
+    summary: input.summary || `${input.stage} stage is active.`,
+    details: compactRecord({
+      elapsed_ms: elapsedMs(state.created_at, at),
+      stage_elapsed_ms: elapsedMs(state.stage_started_at, at),
+      wait_reason: input.wait_reason,
+      blocker: input.blocker,
+      ...input.details
+    })
+  });
+}
+function createRunStatusSnapshot(state, at = timestamp()) {
+  const latestEvent = state.events[state.events.length - 1];
+  const runId = state.run_id || "unknown";
+  return compactRecord({
+    run_id: runId,
+    status: state.status,
+    current_stage: state.current_stage ?? null,
+    state_path: state.state_path ?? null,
+    worktree_path: state.worktree_path ?? null,
+    branch: state.branch ?? null,
+    iterations: state.iterations,
+    last_checkpoint: state.last_checkpoint ?? null,
+    updated_at: state.updated_at,
+    elapsed_ms: elapsedMs(state.created_at, at),
+    stage_elapsed_ms: elapsedMs(state.stage_started_at, at),
+    blocker: state.blocker,
+    latest_event: latestEvent
+  });
+}
+function setRunStatus(state, status, at = timestamp()) {
+  state.status = status;
+  state.ok = status !== "blocked" && status !== "failed";
+  state.updated_at = at;
+  return state;
+}
+
+// src/engine-harness.ts
+function timestamp2() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function createHarnessStatePath(stateDir) {
+  const stamp = timestamp2().replace(/\D/g, "").slice(0, 14) || "unknown";
+  return import_node_path.default.join(stateDir, `riddle-proof-run-${stamp}-${import_node_crypto.default.randomUUID().slice(0, 8)}.json`);
+}
+function ensureParent(filePath) {
+  (0, import_node_fs.mkdirSync)(import_node_path.default.dirname(filePath), { recursive: true });
+}
+function readJson(filePath) {
+  if (!filePath || !(0, import_node_fs.existsSync)(filePath)) return null;
+  try {
+    return JSON.parse((0, import_node_fs.readFileSync)(filePath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function writeJson(filePath, payload) {
+  ensureParent(filePath);
+  (0, import_node_fs.writeFileSync)(filePath, JSON.stringify(payload, null, 2) + "\n");
+}
+function loadRunState(input) {
+  if (input.state) return input.state;
+  const stateDir = input.config?.stateDir || "/tmp";
+  const statePath = input.state_path || input.request.harness_state_path || createHarnessStatePath(stateDir);
+  const existing = readJson(statePath);
+  if (existing?.version === "riddle-proof.run-state.v1" && Array.isArray(existing.events) && existing.request) {
+    return existing;
+  }
+  return createRunState({
+    request: input.request,
+    state_path: statePath
+  });
+}
+function persist(state) {
+  if (state.state_path) writeJson(state.state_path, state);
+}
+function recordEvent(state, event) {
+  appendRunEvent(state, event);
+  persist(state);
+}
+function heartbeat(state, input) {
+  appendStageHeartbeat(state, input);
+  persist(state);
+}
+function jsonParam(payload) {
+  return JSON.stringify(payload);
+}
+function engineStatePath(result, state) {
+  return nonEmptyString(result.state_path) || nonEmptyString(state.request.engine_state_path);
+}
+function fullRiddleState(result, state) {
+  return readJson(engineStatePath(result, state)) || recordValue(result.state) || null;
+}
+function workdirFromState(state) {
+  return nonEmptyString(state?.after_worktree) || nonEmptyString(state?.worktree_path) || null;
+}
+function hasGitDiff(workdir) {
+  if (!workdir || !(0, import_node_fs.existsSync)(workdir)) return false;
+  try {
+    const status = (0, import_node_child_process.execFileSync)("git", ["status", "--porcelain"], {
+      cwd: workdir,
+      encoding: "utf-8",
+      timeout: 1e4
+    });
+    return status.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+function removeEmptyToolArtifacts(workdir) {
+  if (!workdir || !(0, import_node_fs.existsSync)(workdir)) return [];
+  const artifactPath = import_node_path.default.join(workdir, ".codex");
+  if (!(0, import_node_fs.existsSync)(artifactPath)) return [];
+  try {
+    const status = (0, import_node_child_process.execFileSync)("git", ["status", "--porcelain", "--", ".codex"], {
+      cwd: workdir,
+      encoding: "utf-8",
+      timeout: 1e4
+    }).trim();
+    const stat = (0, import_node_fs.statSync)(artifactPath);
+    if (status.startsWith("?? ") && stat.isFile() && stat.size === 0) {
+      (0, import_node_fs.unlinkSync)(artifactPath);
+      return [".codex"];
+    }
+  } catch {
+    return [];
+  }
+  return [];
+}
+function stageFromCheckpoint(result) {
+  const explicitStage = nonEmptyString(result.stage);
+  if (explicitStage) return explicitStage;
+  const checkpoint = String(result.checkpoint || "");
+  if (checkpoint.startsWith("recon_")) return "recon";
+  if (checkpoint.startsWith("author_")) return "author";
+  if (checkpoint.startsWith("implement_")) return "implement";
+  if (checkpoint.startsWith("verify_")) return "verify";
+  if (checkpoint.startsWith("ship_")) return "ship";
+  if (checkpoint.includes("capture")) return "prove";
+  return "setup";
+}
+function stageFromWorkflowParams(params) {
+  const stage = nonEmptyString(params.advance_stage);
+  if (stage) return stage;
+  if (params.ship_after_verify) return "ship";
+  if (params.proof_assessment_json) return "verify";
+  if (params.implementation_notes) return "verify";
+  if (params.author_packet_json) return "implement";
+  if (params.recon_assessment_json) return "author";
+  return "setup";
+}
+function baseContinuation(result) {
+  return {
+    action: "run",
+    state_path: String(result.state_path || ""),
+    continue_from_checkpoint: true
+  };
+}
+function initialRunParams(request, input, state) {
+  return compactRecord({
+    action: "run",
+    repo: request.repo,
+    branch: request.branch,
+    change_request: request.change_request,
+    commit_message: request.commit_message,
+    prod_url: request.prod_url,
+    capture_script: request.capture_script,
+    success_criteria: request.success_criteria,
+    assertions_json: typeof request.assertions === "string" ? request.assertions : request.assertions === void 0 ? void 0 : JSON.stringify(request.assertions),
+    verification_mode: request.verification_mode,
+    reference: request.reference,
+    base_branch: request.base_branch,
+    before_ref: request.before_ref,
+    allow_static_preview_fallback: request.allow_static_preview_fallback,
+    context: request.context,
+    reviewer: request.reviewer,
+    mode: request.mode,
+    build_command: request.build_command,
+    build_output: request.build_output,
+    server_image: request.server_image,
+    server_command: request.server_command,
+    server_port: request.server_port,
+    server_path: request.server_path,
+    use_auth: request.use_auth,
+    color_scheme: request.color_scheme,
+    wait_for_selector: request.wait_for_selector,
+    discord_channel: request.integration_context?.channel_id,
+    discord_thread_id: request.integration_context?.thread_id,
+    discord_message_id: request.integration_context?.message_id,
+    discord_source_url: request.integration_context?.source_url,
+    state_path: request.engine_state_path || state.request.engine_state_path,
+    auto_approve: input.auto_approve ?? request.auto_approve
+  });
+}
+function effectiveShipMode(request, config) {
+  return request.ship_mode || config?.defaultShipMode || "ship";
+}
+function checkpointContinueStage(result) {
+  const resume = recordValue(result.checkpointContract?.resume);
+  return nonEmptyString(resume?.continue_with_stage);
+}
+function recommendedContinuation(result) {
+  const continueStage = checkpointContinueStage(result);
+  if (!continueStage) return null;
+  return {
+    action: "run",
+    state_path: String(result.state_path || ""),
+    advance_stage: continueStage
+  };
+}
+function defaultAwaitingStageContinuation(result) {
+  const contract = recordValue(result.checkpointContract) || {};
+  const stage = nonEmptyString(contract.stage) || nonEmptyString(result.stage) || "";
+  const nextStage = stage === "setup" ? "recon" : stage === "recon" ? "author" : stage === "author" ? "implement" : stage === "implement" || stage === "verify" ? "verify" : "";
+  if (!nextStage) return null;
+  return {
+    action: "run",
+    state_path: String(result.state_path || ""),
+    advance_stage: nextStage
+  };
+}
+function isReadyShipGate(result) {
+  const gate = recordValue(result.shipGate) || recordValue(result.checkpointContract?.ship_gate);
+  return Boolean(gate && gate.ok === true);
+}
+function proofAssessmentRequestsShip(payload) {
+  const decision = String(payload.decision || "");
+  const recommendedStage = String(payload.recommended_stage || "");
+  const continueStage = String(payload.continue_with_stage || "");
+  return decision === "ready_to_ship" || recommendedStage === "ship" || continueStage === "ship";
+}
+function proofAssessmentContinuation(request, result, payload, config) {
+  const proof_assessment_json = jsonParam(payload);
+  if (effectiveShipMode(request, config) === "ship" || !proofAssessmentRequestsShip(payload)) {
+    return { ...baseContinuation(result), proof_assessment_json };
+  }
+  return {
+    action: "run",
+    state_path: String(result.state_path || ""),
+    advance_stage: "verify",
+    proof_assessment_json
+  };
+}
+function contextFor(request, state, result) {
+  return {
+    request,
+    state,
+    engineResult: result,
+    fullRiddleState: fullRiddleState(result, state),
+    checkpoint: String(result.checkpoint || "unknown")
+  };
+}
+function requirePayload(action, payload, state, result) {
+  if (payload.blocker || payload.ok === false) {
+    return payload.blocker || {
+      code: `${action}_blocked`,
+      checkpoint: result.checkpoint || null,
+      message: payload.summary || `${action} did not return a usable payload.`
+    };
+  }
+  if (!payload.payload || typeof payload.payload !== "object") {
+    return {
+      code: `${action}_missing_payload`,
+      checkpoint: result.checkpoint || null,
+      message: `${action} did not return the JSON payload required by the riddle-proof checkpoint.`,
+      details: {
+        run_id: state.run_id,
+        state_path: state.state_path
+      }
+    };
+  }
+  return null;
+}
+function terminalResult(state, status, result, summary, raw = {}) {
+  setRunStatus(state, status);
+  const metadata = normalizeTerminalMetadata({
+    riddleState: result ? fullRiddleState(result, state) : null,
+    engineResult: result
+  });
+  applyTerminalMetadata(state, metadata);
+  persist(state);
+  return createRunResult({
+    state,
+    status,
+    last_summary: summary,
+    metadata,
+    raw: {
+      engine_state_path: result?.state_path || state.request.engine_state_path || null,
+      last_result: result,
+      ...raw
+    }
+  });
+}
+function blockerResult(state, result, blocker) {
+  state.blocker = blocker;
+  recordEvent(state, {
+    kind: "run.blocked",
+    checkpoint: blocker.checkpoint || result?.checkpoint || null,
+    stage: stageFromCheckpoint(result || {}),
+    summary: blocker.message,
+    details: {
+      code: blocker.code,
+      ...blocker.details
+    }
+  });
+  setRunStatus(state, "blocked");
+  persist(state);
+  return createRunResult({
+    state,
+    status: "blocked",
+    last_summary: blocker.message,
+    raw: {
+      engine_state_path: result?.state_path || state.request.engine_state_path || null,
+      last_result: result
+    }
+  });
+}
+function disabledAdapterPayload(action, context) {
+  return {
+    ok: false,
+    blocker: {
+      code: "agent_adapter_not_configured",
+      checkpoint: context.checkpoint,
+      message: `No agent adapter is configured for ${action}. The engine harness reached the checkpoint safely and stopped before faking agent output.`,
+      details: {
+        run_id: context.state.run_id,
+        state_path: context.state.state_path,
+        engine_state_path: context.engineResult.state_path || null,
+        checkpointContract: context.engineResult.checkpointContract || null
+      }
+    }
+  };
+}
+function createDisabledRiddleProofAgentAdapter() {
+  return {
+    assessRecon: (context) => Promise.resolve(disabledAdapterPayload("recon assessment", context)),
+    authorProofPacket: (context) => Promise.resolve(disabledAdapterPayload("proof packet authoring", context)),
+    implementChange: (context) => Promise.resolve(disabledAdapterPayload("implementation", context)),
+    assessProof: (context) => Promise.resolve(disabledAdapterPayload("proof assessment", context))
+  };
+}
+async function resolveEngine(input) {
+  if (typeof input.engine === "function") return input.engine();
+  if (input.engine) return input.engine;
+  const moduleUrl = input.config?.riddleEngineModuleUrl;
+  if (!moduleUrl) {
+    throw new Error("No riddle engine adapter or riddleEngineModuleUrl is configured.");
+  }
+  const mod = await import(moduleUrl);
+  if (typeof mod.createRiddleProofEngine !== "function") {
+    throw new Error(`Riddle engine module does not export createRiddleProofEngine: ${moduleUrl}`);
+  }
+  return mod.createRiddleProofEngine({
+    riddleProofDir: input.config?.riddleProofDir,
+    defaultReviewer: input.config?.defaultReviewer
+  });
+}
+async function handleImplementation(request, state, result, agent) {
+  const context = contextFor(request, state, result);
+  const workdir = workdirFromState(context.fullRiddleState);
+  state.worktree_path = workdir || state.worktree_path;
+  state.branch = nonEmptyString(context.fullRiddleState?.branch) || state.branch;
+  persist(state);
+  if (!workdir || !(0, import_node_fs.existsSync)(workdir)) {
+    return {
+      blocker: {
+        code: "implementation_worktree_missing",
+        checkpoint: result.checkpoint || null,
+        message: "The Riddle Proof engine state does not include an isolated after worktree that exists on disk.",
+        details: {
+          worktree_path: workdir || null,
+          engine_state_path: result.state_path || null
+        }
+      }
+    };
+  }
+  const implementation = await agent.implementChange({ ...context, workdir });
+  if (implementation.blocker || implementation.ok === false) {
+    return {
+      blocker: implementation.blocker || {
+        code: "implementation_blocked",
+        checkpoint: result.checkpoint || null,
+        message: implementation.summary || "Implementation adapter did not complete."
+      }
+    };
+  }
+  const cleanedArtifacts = removeEmptyToolArtifacts(workdir);
+  const diffDetected = implementation.diffDetected === true || hasGitDiff(workdir);
+  if (!diffDetected) {
+    return {
+      blocker: {
+        code: "implementation_diff_missing",
+        checkpoint: result.checkpoint || null,
+        message: "The implementation adapter returned, but the after worktree has no detectable git diff. The harness will not advance to verify.",
+        details: { worktree_path: workdir || null }
+      }
+    };
+  }
+  recordEvent(state, {
+    kind: "agent.implementation.completed",
+    checkpoint: result.checkpoint || null,
+    stage: "implement",
+    summary: implementation.summary || "Implementation adapter reported code changes.",
+    details: {
+      worktree_path: workdir || null,
+      diffDetected,
+      changed_files: implementation.changedFiles || [],
+      cleaned_artifacts: cleanedArtifacts
+    }
+  });
+  return {
+    next: compactRecord({
+      ...baseContinuation(result),
+      advance_stage: "implement",
+      implementation_notes: implementation.implementationNotes || implementation.summary
+    })
+  };
+}
+async function routeCheckpoint(request, state, result, agent, input) {
+  const checkpoint = String(result.checkpoint || "");
+  const context = contextFor(request, state, result);
+  if (!checkpoint) {
+    return {
+      terminal: terminalResult(state, "completed", result, result.summary || "Riddle Proof engine completed.")
+    };
+  }
+  if ([
+    "recon_human_escalation",
+    "verify_human_escalation",
+    "ship_gate_blocked",
+    "verify_required",
+    "verify_supervisor_judgment_required"
+  ].includes(checkpoint) && result.ok === false) {
+    return {
+      blocker: {
+        code: checkpoint,
+        checkpoint,
+        message: result.summary || `Riddle Proof blocked at ${checkpoint}.`,
+        details: { checkpointContract: result.checkpointContract || null }
+      }
+    };
+  }
+  if (checkpoint === "ship_review") {
+    return {
+      terminal: terminalResult(state, "shipped", result, result.summary || "Riddle Proof shipped.")
+    };
+  }
+  if (checkpoint === "verify_ship_ready") {
+    const shipMode = effectiveShipMode(request, input.config);
+    if (shipMode === "ship") {
+      if (!isReadyShipGate(result)) {
+        return {
+          blocker: {
+            code: "ship_gate_not_ready",
+            checkpoint,
+            message: "The harness reached verify_ship_ready, but the ship gate is not passing. It will not call ship.",
+            details: { shipGate: result.shipGate || result.checkpointContract?.ship_gate || null }
+          }
+        };
+      }
+      return { next: { ...baseContinuation(result), ship_after_verify: true } };
+    }
+    return {
+      terminal: terminalResult(state, "ready_to_ship", result, result.summary || "Riddle Proof is ready to ship.", {
+        ship_held: true
+      })
+    };
+  }
+  if (input.dry_run || request.dry_run) {
+    return {
+      blocker: {
+        code: "dry_run_checkpoint",
+        checkpoint,
+        message: "Dry run stopped before applying agent input to the Riddle Proof workflow.",
+        details: { checkpointContract: result.checkpointContract || null }
+      }
+    };
+  }
+  if (checkpoint === "recon_supervisor_judgment") {
+    const assessment = await agent.assessRecon(context);
+    const blocker = requirePayload("recon_assessment", assessment, state, result);
+    if (blocker) return { blocker };
+    recordEvent(state, {
+      kind: "agent.recon_assessment.completed",
+      checkpoint,
+      stage: "recon",
+      summary: assessment.summary,
+      details: { payload: assessment.payload }
+    });
+    return {
+      next: { ...baseContinuation(result), recon_assessment_json: jsonParam(assessment.payload) }
+    };
+  }
+  const continueStage = checkpointContinueStage(result);
+  const checkpointContinuesToAuthor = continueStage === "author";
+  if (checkpoint === "author_supervisor_judgment" || checkpoint === "verify_capture_retry" || checkpoint === "verify_agent_retry" && checkpointContinuesToAuthor) {
+    const packet = await agent.authorProofPacket(context);
+    const blocker = requirePayload("author_packet", packet, state, result);
+    if (blocker) return { blocker };
+    recordEvent(state, {
+      kind: "agent.author_packet.completed",
+      checkpoint,
+      stage: "author",
+      summary: packet.summary,
+      details: { payload: packet.payload }
+    });
+    return {
+      next: { ...baseContinuation(result), author_packet_json: jsonParam(packet.payload) }
+    };
+  }
+  if (checkpoint === "implement_changes_missing" || checkpoint === "implement_required" || checkpoint === "verify_agent_retry" && continueStage === "implement") {
+    return handleImplementation(request, state, result, agent);
+  }
+  if (checkpoint === "implement_review") {
+    return { next: { action: "run", state_path: String(result.state_path || ""), advance_stage: "verify" } };
+  }
+  if (checkpoint === "verify_supervisor_judgment") {
+    const assessment = await agent.assessProof(context);
+    const blocker = requirePayload("proof_assessment", assessment, state, result);
+    if (blocker) return { blocker };
+    const payload = assessment.payload;
+    recordEvent(state, {
+      kind: "agent.proof_assessment.completed",
+      checkpoint,
+      stage: "verify",
+      summary: assessment.summary,
+      details: { payload }
+    });
+    return { next: proofAssessmentContinuation(request, result, payload, input.config) };
+  }
+  if (checkpoint === "verify_agent_retry") {
+    const next = recommendedContinuation(result);
+    if (next) return { next };
+  }
+  if (checkpoint === "awaiting_stage_advance") {
+    const next = recommendedContinuation(result) || defaultAwaitingStageContinuation(result);
+    if (next) {
+      if (String(next.advance_stage || "") === "ship" && effectiveShipMode(request, input.config) !== "ship") {
+        return {
+          terminal: terminalResult(state, "ready_to_ship", result, result.summary || "Riddle Proof is ready to ship.", {
+            ship_held: true
+          })
+        };
+      }
+      return { next };
+    }
+  }
+  if (checkpoint.endsWith("_review")) {
+    const next = recommendedContinuation(result);
+    if (next) return { next };
+  }
+  return {
+    blocker: {
+      code: "unhandled_checkpoint",
+      checkpoint,
+      message: `The harness does not yet know how to safely continue checkpoint ${checkpoint}.`,
+      details: { checkpointContract: result.checkpointContract || null }
+    }
+  };
+}
+function readRiddleProofRunStatus(state_path) {
+  const state = readJson(state_path);
+  if (state?.version !== "riddle-proof.run-state.v1" || !Array.isArray(state.events)) return null;
+  return createRunStatusSnapshot(state);
+}
+async function runRiddleProofEngineHarness(input) {
+  const state = loadRunState(input);
+  state.request = normalizeRunParams({ ...state.request, ...input.request });
+  const request = state.request;
+  const agent = input.agent || createDisabledRiddleProofAgentAdapter();
+  const maxIterations = Math.max(
+    1,
+    Math.trunc(input.max_iterations ?? request.max_iterations ?? input.config?.defaultMaxIterations ?? 8)
+  );
+  state.status = "running";
+  state.ok = void 0;
+  state.blocker = void 0;
+  persist(state);
+  recordEvent(state, {
+    kind: "engine_harness.started",
+    checkpoint: "engine_harness_started",
+    stage: "setup",
+    summary: "Riddle Proof engine harness started.",
+    details: {
+      run_id: state.run_id,
+      state_path: state.state_path,
+      engine_state_path: request.engine_state_path || null,
+      max_iterations: maxIterations,
+      ship_mode: effectiveShipMode(request, input.config)
+    }
+  });
+  let engine;
+  try {
+    engine = await resolveEngine(input);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return blockerResult(state, null, {
+      code: "riddle_engine_not_configured",
+      checkpoint: "engine_resolve_failed",
+      message
+    });
+  }
+  let nextParams = initialRunParams(request, input, state);
+  let lastResult = null;
+  for (let index = 0; index < maxIterations; index += 1) {
+    state.iterations += 1;
+    const stage = stageFromWorkflowParams(nextParams);
+    heartbeat(state, {
+      stage,
+      summary: `${stage} stage is active.`,
+      details: {
+        iteration: state.iterations,
+        run_id: state.run_id,
+        state_path: state.state_path,
+        engine_state_path: nextParams.state_path || null,
+        worktree_path: state.worktree_path || null,
+        branch: state.branch || null
+      }
+    });
+    recordEvent(state, {
+      kind: "engine.call",
+      checkpoint: "engine_call",
+      stage,
+      summary: "Calling Riddle Proof engine.",
+      details: { params: nextParams }
+    });
+    let result;
+    try {
+      result = await engine.execute(nextParams);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return blockerResult(state, lastResult, {
+        code: "riddle_engine_exception",
+        checkpoint: "engine_call_failed",
+        message
+      });
+    }
+    lastResult = result;
+    const engineState = engineStatePath(result, state);
+    if (engineState) state.request.engine_state_path = engineState;
+    state.last_checkpoint = result.checkpoint || state.last_checkpoint || null;
+    const resultStage = stageFromCheckpoint(result);
+    heartbeat(state, {
+      stage: resultStage,
+      summary: `${resultStage} stage is active.`,
+      details: {
+        iteration: state.iterations,
+        run_id: state.run_id,
+        state_path: state.state_path,
+        engine_state_path: engineState || null,
+        checkpoint: result.checkpoint || null
+      }
+    });
+    recordEvent(state, {
+      kind: "engine.result",
+      checkpoint: result.checkpoint || null,
+      stage: resultStage,
+      summary: result.summary,
+      details: {
+        ok: result.ok ?? null,
+        engine_state_path: engineState || null,
+        checkpoint: result.checkpoint || null
+      }
+    });
+    const routed = await routeCheckpoint(request, state, result, agent, input);
+    if (routed.terminal) return routed.terminal;
+    if (routed.blocker) return blockerResult(state, result, routed.blocker);
+    if (!routed.next) {
+      return blockerResult(state, result, {
+        code: "missing_next_step",
+        checkpoint: result.checkpoint || null,
+        message: "The harness route returned no next step."
+      });
+    }
+    nextParams = routed.next;
+  }
+  return blockerResult(state, lastResult, {
+    code: "max_iterations_reached",
+    checkpoint: lastResult?.checkpoint || null,
+    message: `The harness reached max_iterations=${maxIterations} before the proof was ready or shipped.`,
+    details: {
+      nextParams,
+      lastCheckpoint: lastResult?.checkpoint || null,
+      lastSummary: lastResult?.summary || null
+    }
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createDisabledRiddleProofAgentAdapter,
+  readRiddleProofRunStatus,
+  runRiddleProofEngineHarness
+});