@riddledc/riddle-proof 0.7.225 → 0.7.227

package/dist/spec/checkpoint.cjs

@@ -0,0 +1,807 @@
+"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/spec/checkpoint.ts
+var checkpoint_exports = {};
+__export(checkpoint_exports, {
+  RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION: () => RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION,
+  RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION: () => RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION,
+  authorPacketPayloadFromCheckpointResponse: () => authorPacketPayloadFromCheckpointResponse,
+  buildAuthorCheckpointPacket: () => buildAuthorCheckpointPacket,
+  buildCheckpointPacketForEngineResult: () => buildCheckpointPacketForEngineResult,
+  buildProofAssessmentCheckpointPacket: () => buildProofAssessmentCheckpointPacket,
+  buildStageCheckpointPacket: () => buildStageCheckpointPacket,
+  checkpointResponseIdentity: () => checkpointResponseIdentity,
+  checkpointSummaryFromState: () => checkpointSummaryFromState,
+  createCheckpointResponseTemplate: () => createCheckpointResponseTemplate,
+  isDuplicateCheckpointResponse: () => isDuplicateCheckpointResponse,
+  normalizeCheckpointResponse: () => normalizeCheckpointResponse,
+  proofContractFromAuthorCheckpointResponse: () => proofContractFromAuthorCheckpointResponse,
+  statePathsForRunState: () => statePathsForRunState
+});
+module.exports = __toCommonJS(checkpoint_exports);
+
+// src/checkpoint.ts
+var import_node_crypto = __toESM(require("crypto"), 1);
+
+// src/result.ts
+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;
+}
+
+// src/checkpoint.ts
+var RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION = "riddle-proof.checkpoint.v1";
+var RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION = "riddle-proof.checkpoint_response.v1";
+function timestamp() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function jsonCloneRecord(value) {
+  const record = recordValue(value);
+  if (!record) return void 0;
+  try {
+    return JSON.parse(JSON.stringify(record));
+  } catch {
+    return { ...record };
+  }
+}
+function jsonCloneValue(value) {
+  if (value === void 0 || value === null) return void 0;
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return value;
+  }
+}
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  const record = recordValue(value);
+  if (record) {
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+function compactText(value, limit = 1600) {
+  const text = nonEmptyString(value);
+  if (!text) return void 0;
+  return text.length <= limit ? text : `${text.slice(0, limit - 20).trimEnd()}...`;
+}
+function statePathsForRunState(state, engineStatePath) {
+  return compactRecord({
+    wrapper_state_path: state.state_path || state.request.harness_state_path || null,
+    engine_state_path: engineStatePath || state.request.engine_state_path || null,
+    resume_state_path: engineStatePath || state.request.engine_state_path || null
+  });
+}
+function responseSchemaForAuthorPacket() {
+  return {
+    type: "object",
+    required: ["version", "run_id", "checkpoint", "decision", "summary", "payload", "created_at"],
+    additionalProperties: false,
+    properties: {
+      version: { const: RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION },
+      run_id: { type: "string" },
+      checkpoint: { type: "string" },
+      resume_token: { type: "string" },
+      decision: {
+        type: "string",
+        enum: ["author_packet", "needs_recon", "blocked", "human_review"]
+      },
+      summary: { type: "string" },
+      payload: {
+        type: "object",
+        description: "For decision=author_packet, provide the proof packet itself or {author_packet:{...}} with proof_plan and capture_script."
+      },
+      reasons: { type: "array", items: { type: "string" } },
+      continue_with_stage: { type: "string", enum: ["author", "recon"] },
+      source: {
+        type: "object",
+        properties: {
+          kind: { type: "string" },
+          session_id: { type: "string" },
+          user_id: { type: "string" }
+        }
+      },
+      created_at: { type: "string" }
+    }
+  };
+}
+function responseSchemaForProofAssessmentPacket() {
+  return {
+    type: "object",
+    required: ["version", "run_id", "checkpoint", "decision", "summary", "created_at"],
+    additionalProperties: false,
+    properties: {
+      version: { const: RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION },
+      run_id: { type: "string" },
+      checkpoint: { type: "string" },
+      resume_token: { type: "string" },
+      decision: {
+        type: "string",
+        enum: [
+          "ready_to_ship",
+          "needs_richer_proof",
+          "revise_capture",
+          "needs_recon",
+          "needs_implementation",
+          "blocked",
+          "human_review"
+        ]
+      },
+      summary: { type: "string" },
+      payload: {
+        type: "object",
+        description: "Optional structured assessment details, including recommended_stage, continue_with_stage, visual_delta notes, or blocker diagnostics."
+      },
+      reasons: { type: "array", items: { type: "string" } },
+      continue_with_stage: { type: "string", enum: ["ship", "author", "implement", "recon", "verify"] },
+      source: {
+        type: "object",
+        properties: {
+          kind: { type: "string" },
+          session_id: { type: "string" },
+          user_id: { type: "string" }
+        }
+      },
+      created_at: { type: "string" }
+    }
+  };
+}
+function responseSchemaForReconPacket() {
+  return {
+    type: "object",
+    required: ["version", "run_id", "checkpoint", "decision", "summary", "created_at"],
+    additionalProperties: false,
+    properties: {
+      version: { const: RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION },
+      run_id: { type: "string" },
+      checkpoint: { type: "string" },
+      resume_token: { type: "string" },
+      decision: {
+        type: "string",
+        enum: ["ready_for_author", "retry_recon", "recon_stuck", "needs_recon", "blocked", "human_review"]
+      },
+      summary: { type: "string" },
+      payload: {
+        type: "object",
+        description: "Optional recon assessment details such as baseline_understanding, refined_inputs, reasons, or diagnostic blocker context."
+      },
+      reasons: { type: "array", items: { type: "string" } },
+      continue_with_stage: { type: "string", enum: ["recon", "author"] },
+      source: {
+        type: "object",
+        properties: {
+          kind: { type: "string" },
+          session_id: { type: "string" },
+          user_id: { type: "string" }
+        }
+      },
+      created_at: { type: "string" }
+    }
+  };
+}
+function responseSchemaForImplementationPacket() {
+  return {
+    type: "object",
+    required: ["version", "run_id", "checkpoint", "decision", "summary", "created_at"],
+    additionalProperties: false,
+    properties: {
+      version: { const: RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION },
+      run_id: { type: "string" },
+      checkpoint: { type: "string" },
+      resume_token: { type: "string" },
+      decision: {
+        type: "string",
+        enum: ["implementation_complete", "needs_author", "needs_recon", "blocked", "human_review"]
+      },
+      summary: { type: "string" },
+      payload: {
+        type: "object",
+        description: "Implementation details such as changed_files, tests_run, and implementation_notes. The changed worktree must contain a real git diff before verify can advance."
+      },
+      reasons: { type: "array", items: { type: "string" } },
+      continue_with_stage: { type: "string", enum: ["implement", "verify", "author", "recon"] },
+      source: {
+        type: "object",
+        properties: {
+          kind: { type: "string" },
+          session_id: { type: "string" },
+          user_id: { type: "string" }
+        }
+      },
+      created_at: { type: "string" }
+    }
+  };
+}
+function responseSchemaForAdvancePacket(stage) {
+  return {
+    type: "object",
+    required: ["version", "run_id", "checkpoint", "decision", "summary", "created_at"],
+    additionalProperties: false,
+    properties: {
+      version: { const: RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION },
+      run_id: { type: "string" },
+      checkpoint: { type: "string" },
+      resume_token: { type: "string" },
+      decision: {
+        type: "string",
+        enum: ["continue_stage", "retry_stage", "needs_recon", "needs_implementation", "blocked", "human_review"]
+      },
+      summary: { type: "string" },
+      payload: { type: "object" },
+      reasons: { type: "array", items: { type: "string" } },
+      continue_with_stage: { type: "string", enum: ["recon", "author", "implement", "verify", "ship", stage] },
+      source: {
+        type: "object",
+        properties: {
+          kind: { type: "string" },
+          session_id: { type: "string" },
+          user_id: { type: "string" }
+        }
+      },
+      created_at: { type: "string" }
+    }
+  };
+}
+function resumeTokenFor(input) {
+  const hash = import_node_crypto.default.createHash("sha256").update(JSON.stringify(input)).digest("hex").slice(0, 24);
+  return `rpchk_${hash}`;
+}
+function artifactsFromState(state) {
+  const artifacts = [];
+  for (const role of ["before", "prod", "after"]) {
+    const url = nonEmptyString(state?.[`${role}_cdn`]);
+    if (url) artifacts.push({ role, url, name: `${role}.png`, mime_type: "image/png" });
+  }
+  const authorRequest = recordValue(state?.author_request);
+  const latestAttempt = recordValue(authorRequest?.latest_attempt);
+  const observations = recordValue(latestAttempt?.observations);
+  for (const [label, observation] of Object.entries(observations || {})) {
+    const record = recordValue(observation);
+    const url = nonEmptyString(record?.url);
+    if (url && !artifacts.some((artifact) => artifact.url === url)) {
+      artifacts.push({
+        role: label === "before" || label === "prod" ? label : "json",
+        url,
+        name: `${label}-observation`,
+        summary: compactText(record?.reason, 240)
+      });
+    }
+  }
+  return artifacts.slice(0, 16);
+}
+function stageFromCheckpoint(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.startsWith("pr_sync_")) return "notify";
+  if (checkpoint.includes("capture")) return "prove";
+  return "setup";
+}
+function allowedDecisionsForStage(stage, checkpoint) {
+  if (stage === "recon") return ["ready_for_author", "retry_recon", "recon_stuck", "blocked", "human_review"];
+  if (stage === "implement") return ["implementation_complete", "needs_author", "needs_recon", "blocked", "human_review"];
+  if (stage === "ship") return ["continue_stage", "needs_implementation", "needs_recon", "blocked", "human_review"];
+  if (checkpoint === "awaiting_stage_advance") return ["continue_stage", "retry_stage", "blocked", "human_review"];
+  return ["continue_stage", "needs_recon", "needs_implementation", "blocked", "human_review"];
+}
+function packetKindForStage(stage, checkpoint) {
+  if (stage === "recon") return "assess_recon";
+  if (stage === "implement") return "implement_change";
+  if (checkpoint.includes("human")) return "human_review";
+  return "advance_decision";
+}
+function responseSchemaForStage(stage, checkpoint) {
+  if (stage === "recon") return responseSchemaForReconPacket();
+  if (stage === "implement") return responseSchemaForImplementationPacket();
+  return responseSchemaForAdvancePacket(stage);
+}
+function questionForStage(stage, checkpoint) {
+  if (stage === "recon") {
+    return "Assess the baseline/recon evidence. Return ready_for_author only when the baseline is trustworthy; otherwise choose retry_recon, recon_stuck, blocked, or human_review.";
+  }
+  if (stage === "implement") {
+    return "Implement the requested change in the after worktree, leave a real git diff, then return implementation_complete with changed_files/tests_run/implementation_notes. Choose blocked or human_review if implementation cannot honestly advance.";
+  }
+  if (stage === "ship") {
+    return "Assess whether the ship gate can continue. Return continue_stage only if proof, PR, and policy gates are satisfied; otherwise route to the appropriate earlier stage or block with a concrete reason.";
+  }
+  return "Choose the next Riddle Proof stage for this durable run, or block with a concrete reason if the run cannot honestly advance.";
+}
+function buildStageCheckpointPacket(input) {
+  const checkpoint = nonEmptyString(input.engineResult.checkpoint) || "stage_checkpoint";
+  const stage = nonEmptyString(input.engineResult.stage) || stageFromCheckpoint(checkpoint);
+  const runId = input.runState.run_id || "unknown";
+  const fullState = input.fullRiddleState || {};
+  const decisionDetails = recordValue(input.engineResult.decisionRequest?.details);
+  const checkpointContract = recordValue(input.engineResult.checkpointContract);
+  const summary = nonEmptyString(input.engineResult.summary) || nonEmptyString(fullState.stage_summary) || `${stage} checkpoint needs a supervising decision.`;
+  const kind = packetKindForStage(stage, checkpoint);
+  return {
+    version: RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION,
+    run_id: runId,
+    state_path: input.runState.state_path,
+    stage,
+    checkpoint,
+    kind,
+    summary,
+    question: questionForStage(stage, checkpoint),
+    change_request: input.request.change_request || nonEmptyString(fullState.change_request) || "",
+    context: input.request.context,
+    artifacts: artifactsFromState(fullState),
+    state_excerpt: compactRecord({
+      repo: input.request.repo || fullState.repo,
+      branch: input.request.branch || fullState.branch,
+      after_worktree: fullState.after_worktree || input.runState.worktree_path,
+      verification_mode: input.request.verification_mode || fullState.verification_mode,
+      reference: input.request.reference || fullState.reference,
+      server_path: fullState.server_path,
+      wait_for_selector: fullState.wait_for_selector,
+      recon_status: fullState.recon_status,
+      author_status: fullState.author_status,
+      implementation_status: fullState.implementation_status,
+      verify_status: fullState.verify_status,
+      stage_decision_request: jsonCloneRecord(fullState.stage_decision_request)
+    }),
+    evidence_excerpt: compactRecord({
+      before_cdn: fullState.before_cdn || null,
+      prod_cdn: fullState.prod_cdn || null,
+      after_cdn: fullState.after_cdn || null,
+      recon_results: jsonCloneRecord(fullState.recon_results),
+      checkpoint_contract: jsonCloneRecord(checkpointContract),
+      decision_details: jsonCloneRecord(decisionDetails)
+    }),
+    allowed_decisions: allowedDecisionsForStage(stage, checkpoint),
+    response_schema: responseSchemaForStage(stage, checkpoint),
+    routing_hint: {
+      suggested_role: stage === "implement" ? "builder_agent" : checkpoint.includes("human") ? "human" : "main_agent",
+      visibility: input.visibility || "quiet",
+      urgency: stage === "ship" ? "high" : "normal",
+      can_auto_answer: input.visibility !== "manual"
+    },
+    resume_token: resumeTokenFor({
+      runId,
+      statePath: input.engineResult.state_path || input.request.engine_state_path || null,
+      checkpoint,
+      stage
+    }),
+    created_at: input.created_at || timestamp()
+  };
+}
+function buildAuthorCheckpointPacket(input) {
+  const checkpoint = nonEmptyString(input.engineResult.checkpoint) || "author_supervisor_judgment";
+  const stage = "author";
+  const runId = input.runState.run_id || "unknown";
+  const fullState = input.fullRiddleState || {};
+  const decisionDetails = recordValue(input.engineResult.decisionRequest?.details);
+  const authorRequest = recordValue(fullState.author_request) || recordValue(fullState.proof_plan_request) || recordValue(decisionDetails?.authorRequest) || {};
+  const fallbackDefaults = recordValue(authorRequest.fallback_defaults) || {};
+  const reconResults = recordValue(fullState.recon_results);
+  const checkpointContract = recordValue(input.engineResult.checkpointContract);
+  const summary = nonEmptyString(input.engineResult.summary) || nonEmptyString(fullState.author_summary) || "Author checkpoint needs a supervising proof packet.";
+  return {
+    version: RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION,
+    run_id: runId,
+    state_path: input.runState.state_path,
+    stage,
+    checkpoint,
+    kind: "author_proof",
+    summary,
+    question: "Author the proof packet for this Riddle Proof run. Return a CheckpointResponse with decision=author_packet and payload containing proof_plan and capture_script.",
+    change_request: input.request.change_request || nonEmptyString(fullState.change_request) || "",
+    context: input.request.context,
+    artifacts: artifactsFromState(fullState),
+    state_excerpt: compactRecord({
+      repo: input.request.repo || fullState.repo,
+      branch: input.request.branch || fullState.branch,
+      verification_mode: input.request.verification_mode || fullState.verification_mode,
+      reference: input.request.reference || fullState.reference,
+      server_path: fullState.server_path,
+      wait_for_selector: fullState.wait_for_selector,
+      author_summary: fullState.author_summary,
+      author_request: jsonCloneRecord(authorRequest),
+      recon_baseline_understanding: jsonCloneRecord(fullState.recon_baseline_understanding),
+      fallback_defaults: jsonCloneRecord(fallbackDefaults)
+    }),
+    evidence_excerpt: compactRecord({
+      recon_results: jsonCloneRecord(reconResults),
+      checkpoint_contract: jsonCloneRecord(checkpointContract)
+    }),
+    allowed_decisions: ["author_packet", "needs_recon", "blocked", "human_review"],
+    response_schema: responseSchemaForAuthorPacket(),
+    routing_hint: {
+      suggested_role: "proof_author",
+      visibility: input.visibility || "quiet",
+      urgency: "normal",
+      can_auto_answer: input.visibility !== "manual"
+    },
+    resume_token: resumeTokenFor({
+      runId,
+      statePath: input.engineResult.state_path || input.request.engine_state_path || null,
+      checkpoint,
+      stage
+    }),
+    created_at: input.created_at || timestamp()
+  };
+}
+function visualDeltaFromState(fullState) {
+  const bundle = recordValue(fullState.evidence_bundle);
+  const after = recordValue(bundle?.after);
+  const afterDelta = recordValue(after?.visual_delta);
+  if (afterDelta && Object.keys(afterDelta).length) return afterDelta;
+  const proofAssessmentRequest = recordValue(fullState.proof_assessment_request);
+  return recordValue(proofAssessmentRequest?.visual_delta) || null;
+}
+function normalizedText(value) {
+  return typeof value === "string" ? value.trim().toLowerCase() : "";
+}
+function noImplementationModeForCheckpoint(request, fullState) {
+  const requestRecord = recordValue(request) || {};
+  const mode = normalizedText(
+    requestRecord.mode || requestRecord.workflow_mode || fullState.mode || fullState.workflow_mode
+  );
+  const implementationMode = normalizedText(requestRecord.implementation_mode || fullState.implementation_mode);
+  const requireDiff = requestRecord.require_diff ?? fullState.require_diff;
+  const allowCodeChanges = requestRecord.allow_code_changes ?? fullState.allow_code_changes;
+  return mode === "audit" || mode === "profile" || implementationMode === "none" || requireDiff === false || allowCodeChanges === false;
+}
+function visualDeltaNotApplicableForNoImplementation(visualDelta) {
+  if (String(visualDelta?.status || "").trim() !== "not_applicable") return false;
+  const reason = String(visualDelta?.reason || "").toLowerCase();
+  return reason.includes("audit/no-diff") || reason.includes("does not require a before/after implementation delta");
+}
+function verificationModeRequiresVisualDelta(value) {
+  const mode = String(value || "proof").trim().toLowerCase();
+  return [
+    "visual",
+    "render",
+    "interaction",
+    "ui",
+    "layout",
+    "screenshot",
+    "canvas",
+    "animation"
+  ].includes(mode);
+}
+function visualDeltaIssueCode(visualDelta, required) {
+  const status = String(visualDelta?.status || "").trim();
+  const reason = String(visualDelta?.reason || "").toLowerCase();
+  if (status === "unmeasured") {
+    if (reason.includes("fetch") || reason.includes("allowlist") || reason.includes("registered domain") || reason.includes("high risk") || reason.includes("comparator")) {
+      return "comparator_fetch_blocked";
+    }
+    return "visual_delta_unmeasured";
+  }
+  if (status === "measured" && visualDelta?.passed === false) return "semantic_proof_failed";
+  if (required && status !== "measured") return "visual_delta_unmeasured";
+  return null;
+}
+function buildProofAssessmentCheckpointPacket(input) {
+  const checkpoint = nonEmptyString(input.engineResult.checkpoint) || "verify_supervisor_judgment";
+  const stage = "verify";
+  const runId = input.runState.run_id || "unknown";
+  const fullState = input.fullRiddleState || {};
+  const proofAssessmentRequest = recordValue(fullState.proof_assessment_request) || recordValue(recordValue(fullState.verify_decision_request)?.assessment_request) || recordValue(input.engineResult.decisionRequest?.details) || {};
+  const bundle = recordValue(fullState.evidence_bundle);
+  const artifactContract = recordValue(proofAssessmentRequest.artifact_contract) || recordValue(bundle?.artifact_contract);
+  const requiredSignals = recordValue(recordValue(artifactContract)?.required);
+  const visualDelta = visualDeltaFromState(fullState);
+  const verificationMode = nonEmptyString(bundle?.verification_mode) || nonEmptyString(fullState.verification_mode) || nonEmptyString(input.request.verification_mode) || "proof";
+  const noImplementationMode = noImplementationModeForCheckpoint(input.request, fullState);
+  const noImplementationVisualDelta = visualDeltaNotApplicableForNoImplementation(visualDelta);
+  const visualDeltaRequired = !noImplementationMode && !noImplementationVisualDelta && requiredSignals?.visual_delta !== false && (requiredSignals?.visual_delta === true || verificationModeRequiresVisualDelta(verificationMode));
+  const evidenceIssueCode = visualDeltaIssueCode(visualDelta, visualDeltaRequired);
+  const summary = nonEmptyString(input.engineResult.summary) || nonEmptyString(fullState.verify_summary) || "Verify captured evidence and needs a supervising proof assessment.";
+  const recoveryHint = evidenceIssueCode ? "Required visual_delta evidence is incomplete. Keep this same run in verify/evidence recovery with decision=revise_capture and continue_with_stage=verify unless the evidence proves an implementation or recon problem." : "Assess whether the current artifacts prove the requested change, then choose the next stage.";
+  return {
+    version: RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION,
+    run_id: runId,
+    state_path: input.runState.state_path,
+    stage,
+    checkpoint,
+    kind: evidenceIssueCode ? "recover_evidence" : "assess_proof",
+    summary,
+    question: `Assess the current Riddle Proof evidence. ${recoveryHint} Return a CheckpointResponse using one allowed decision.`,
+    change_request: input.request.change_request || nonEmptyString(fullState.change_request) || "",
+    context: input.request.context,
+    artifacts: artifactsFromState(fullState),
+    state_excerpt: compactRecord({
+      repo: input.request.repo || fullState.repo,
+      branch: input.request.branch || fullState.branch,
+      verification_mode: verificationMode,
+      reference: input.request.reference || fullState.reference,
+      server_path: fullState.server_path,
+      wait_for_selector: fullState.wait_for_selector,
+      implementation_status: fullState.implementation_status,
+      implementation_summary: fullState.implementation_summary,
+      changed_files: jsonCloneValue(fullState.changed_files),
+      proof_plan: compactText(fullState.proof_plan, 1200)
+    }),
+    evidence_excerpt: compactRecord({
+      before_cdn: fullState.before_cdn || null,
+      prod_cdn: fullState.prod_cdn || null,
+      after_cdn: fullState.after_cdn || null,
+      visual_delta_required: visualDeltaRequired,
+      visual_delta_ready: !visualDeltaRequired || visualDelta?.status === "measured" && visualDelta?.passed === true,
+      visual_delta: jsonCloneRecord(visualDelta),
+      evidence_issue_code: evidenceIssueCode,
+      proof_assessment_request: jsonCloneRecord(proofAssessmentRequest),
+      verify_decision_request: jsonCloneRecord(fullState.verify_decision_request),
+      checkpoint_contract: jsonCloneRecord(input.engineResult.checkpointContract)
+    }),
+    artifact_contract: jsonCloneRecord(artifactContract),
+    allowed_decisions: [
+      "ready_to_ship",
+      "needs_richer_proof",
+      "revise_capture",
+      "needs_recon",
+      "needs_implementation",
+      "blocked",
+      "human_review"
+    ],
+    response_schema: responseSchemaForProofAssessmentPacket(),
+    routing_hint: {
+      suggested_role: evidenceIssueCode ? "proof_judge" : "proof_judge",
+      visibility: input.visibility || "quiet",
+      urgency: evidenceIssueCode ? "high" : "normal",
+      can_auto_answer: input.visibility !== "manual"
+    },
+    resume_token: resumeTokenFor({
+      runId,
+      statePath: input.engineResult.state_path || input.request.engine_state_path || null,
+      checkpoint,
+      stage
+    }),
+    created_at: input.created_at || timestamp()
+  };
+}
+function buildCheckpointPacketForEngineResult(input) {
+  const checkpoint = nonEmptyString(input.engineResult.checkpoint) || "";
+  if (checkpoint === "verify_supervisor_judgment" || checkpoint === "verify_supervisor_judgment_required" || checkpoint === "verify_human_escalation") {
+    return buildProofAssessmentCheckpointPacket(input);
+  }
+  const resume = recordValue(input.engineResult.checkpointContract?.resume);
+  const continueStage = nonEmptyString(resume?.continue_with_stage);
+  if (checkpoint === "author_supervisor_judgment" || checkpoint === "verify_capture_retry" || checkpoint === "verify_agent_retry" && continueStage === "author") {
+    return buildAuthorCheckpointPacket(input);
+  }
+  return buildStageCheckpointPacket(input);
+}
+function normalizeCheckpointResponse(value) {
+  const record = recordValue(value);
+  if (!record) return null;
+  const version = nonEmptyString(record.version);
+  const runId = nonEmptyString(record.run_id);
+  const checkpoint = nonEmptyString(record.checkpoint);
+  const decision = nonEmptyString(record.decision);
+  const summary = nonEmptyString(record.summary);
+  if (version !== RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION || !runId || !checkpoint || !decision || !summary) {
+    return null;
+  }
+  return compactRecord({
+    version: RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION,
+    run_id: runId,
+    checkpoint,
+    resume_token: nonEmptyString(record.resume_token),
+    decision,
+    summary,
+    payload: jsonCloneRecord(record.payload),
+    reasons: Array.isArray(record.reasons) ? record.reasons.filter((item) => typeof item === "string") : void 0,
+    continue_with_stage: nonEmptyString(record.continue_with_stage),
+    source: jsonCloneRecord(record.source),
+    created_at: nonEmptyString(record.created_at) || timestamp()
+  });
+}
+function defaultContinueStage(packet, decision) {
+  if (decision === "ready_for_author" || decision === "author_packet" || decision === "needs_author") return "author";
+  if (decision === "implementation_complete") return "verify";
+  if (decision === "ready_to_ship") return "ship";
+  if (decision === "revise_capture") return "verify";
+  if (decision === "retry_recon" || decision === "recon_stuck" || decision === "needs_recon") return "recon";
+  if (decision === "needs_implementation") return "implement";
+  if (decision === "continue_stage" || decision === "retry_stage") return packet.stage;
+  return void 0;
+}
+function templatePayloadFor(packet, decision) {
+  if (decision === "author_packet") {
+    return {
+      proof_plan: "TODO: describe the exact proof plan and stop condition.",
+      capture_script: "TODO: provide the capture script that collects required artifacts/evidence.",
+      summary: "TODO: summarize why this proof packet targets the requested change."
+    };
+  }
+  if (decision === "implementation_complete") {
+    return {
+      changed_files: [],
+      tests_run: [],
+      implementation_notes: "TODO: summarize the direct edits made in the after worktree."
+    };
+  }
+  if (decision === "ready_for_author") {
+    return {
+      baseline_understanding: {
+        reference: "TODO",
+        target_route: "TODO",
+        before_evidence_url: "TODO",
+        visible_before_state: "TODO",
+        relevant_elements: [],
+        requested_change: packet.change_request,
+        proof_focus: "TODO",
+        stop_condition: "TODO",
+        quality_risks: []
+      },
+      refined_inputs: {
+        server_path: null,
+        wait_for_selector: null,
+        reference: null
+      }
+    };
+  }
+  if (packet.kind === "assess_proof" || packet.kind === "recover_evidence" || packet.stage === "verify") {
+    return {
+      recommended_stage: defaultContinueStage(packet, decision) || packet.stage,
+      evidence_issue_code: packet.evidence_excerpt?.evidence_issue_code || null,
+      visual_delta: packet.evidence_excerpt?.visual_delta || null
+    };
+  }
+  return void 0;
+}
+function createCheckpointResponseTemplate(packet, input = {}) {
+  const allowed = Array.isArray(packet.allowed_decisions) ? packet.allowed_decisions : [];
+  const decision = input.decision && allowed.includes(input.decision) ? input.decision : allowed[0] || "blocked";
+  const continueStage = input.continue_with_stage || defaultContinueStage(packet, decision);
+  return compactRecord({
+    version: RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION,
+    run_id: packet.run_id,
+    checkpoint: packet.checkpoint,
+    resume_token: packet.resume_token,
+    decision,
+    summary: input.summary || `TODO: explain checkpoint decision ${decision}.`,
+    payload: input.payload || templatePayloadFor(packet, decision),
+    reasons: input.reasons || ["TODO: replace with concrete reason(s)."],
+    continue_with_stage: continueStage,
+    source: {
+      kind: input.source_kind || "codex"
+    },
+    created_at: input.created_at || timestamp()
+  });
+}
+function checkpointSummaryFromState(state, engineStatePath) {
+  const history = state.checkpoint_history || [];
+  const packets = history.filter((entry) => entry.packet);
+  const responses = history.filter((entry) => entry.response);
+  const duplicateResponses = (state.events || []).filter((event) => event.kind === "checkpoint.response.duplicate");
+  const latestPacketEntry = [...history].reverse().find((entry) => entry.packet);
+  const latestResponseEntry = [...history].reverse().find((entry) => entry.response);
+  const latestPacket = state.checkpoint_packet || latestPacketEntry?.packet;
+  const latestResponse = latestResponseEntry?.response;
+  const latestResumeToken = latestPacket?.resume_token || null;
+  const latestResponseToken = latestResponse?.resume_token || null;
+  const tokenMatches = latestResumeToken && latestResponseToken ? latestResumeToken === latestResponseToken : latestResumeToken || latestResponseToken ? false : null;
+  return compactRecord({
+    pending: Boolean(state.checkpoint_packet),
+    packet_count: packets.length,
+    response_count: responses.length,
+    duplicate_response_count: duplicateResponses.length,
+    latest_checkpoint: state.checkpoint_packet?.checkpoint || latestResponse?.checkpoint || state.last_checkpoint || null,
+    latest_stage: state.checkpoint_packet?.stage || latestResponse?.continue_with_stage || state.current_stage || null,
+    latest_kind: state.checkpoint_packet?.kind || latestPacket?.kind || null,
+    latest_decision: latestResponse?.decision || null,
+    latest_packet_summary: latestPacket?.summary || null,
+    latest_response_summary: latestResponse?.summary || null,
+    latest_resume_token: latestResumeToken,
+    latest_response_token: latestResponseToken,
+    token_matches: tokenMatches,
+    last_packet_at: latestPacketEntry?.ts || null,
+    last_response_at: latestResponseEntry?.ts || null,
+    state_paths: statePathsForRunState(state, engineStatePath)
+  });
+}
+function isDuplicateCheckpointResponse(state, response) {
+  const identity = checkpointResponseIdentity(response);
+  return (state.checkpoint_history || []).some((entry) => entry.response ? checkpointResponseIdentity(entry.response) === identity : false);
+}
+function checkpointResponseIdentity(response) {
+  const logicalResponse = compactRecord({
+    run_id: response.run_id,
+    checkpoint: response.checkpoint,
+    resume_token: response.resume_token,
+    decision: response.decision,
+    summary: response.summary,
+    payload: response.payload,
+    reasons: response.reasons,
+    continue_with_stage: response.continue_with_stage,
+    source: response.source
+  });
+  return import_node_crypto.default.createHash("sha256").update(stableJson(logicalResponse)).digest("hex").slice(0, 24);
+}
+function authorPacketPayloadFromCheckpointResponse(response) {
+  if (response.decision !== "author_packet") return null;
+  const payload = recordValue(response.payload);
+  if (!payload) return null;
+  const nested = recordValue(payload.author_packet);
+  const candidate = nested || payload;
+  if (!nonEmptyString(candidate.proof_plan) || !nonEmptyString(candidate.capture_script)) return null;
+  return candidate;
+}
+function proofContractFromAuthorCheckpointResponse(response, packet, payload) {
+  const refinedInputs = recordValue(payload.refined_inputs) || {};
+  return compactRecord({
+    version: "riddle-proof.proof-contract.v1",
+    checkpoint: packet.checkpoint,
+    source_response: compactRecord({
+      run_id: response.run_id,
+      checkpoint: response.checkpoint,
+      resume_token: response.resume_token,
+      decision: response.decision,
+      summary: response.summary,
+      created_at: response.created_at
+    }),
+    proof_plan: nonEmptyString(payload.proof_plan),
+    capture_script: nonEmptyString(payload.capture_script),
+    artifact_contract: jsonCloneRecord(payload.artifact_contract),
+    assertions: jsonCloneValue(payload.assertions),
+    baseline_understanding: jsonCloneRecord(payload.baseline_understanding) || jsonCloneRecord(payload.recon_baseline_understanding) || jsonCloneRecord(packet.state_excerpt?.recon_baseline_understanding),
+    route_assumptions: compactRecord({
+      server_path: nonEmptyString(refinedInputs.server_path) || nonEmptyString(payload.server_path) || nonEmptyString(packet.state_excerpt?.server_path),
+      wait_for_selector: nonEmptyString(refinedInputs.wait_for_selector) || nonEmptyString(payload.wait_for_selector) || nonEmptyString(packet.state_excerpt?.wait_for_selector),
+      reference: nonEmptyString(refinedInputs.reference) || nonEmptyString(payload.reference),
+      expected_path: nonEmptyString(payload.expected_path) || nonEmptyString(refinedInputs.expected_path)
+    }),
+    stop_condition: nonEmptyString(payload.stop_condition),
+    rationale: jsonCloneValue(payload.rationale),
+    verdict_dimensions: jsonCloneRecord(payload.verdict_dimensions),
+    payload: jsonCloneRecord(payload),
+    created_at: timestamp()
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION,
+  RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION,
+  authorPacketPayloadFromCheckpointResponse,
+  buildAuthorCheckpointPacket,
+  buildCheckpointPacketForEngineResult,
+  buildProofAssessmentCheckpointPacket,
+  buildStageCheckpointPacket,
+  checkpointResponseIdentity,
+  checkpointSummaryFromState,
+  createCheckpointResponseTemplate,
+  isDuplicateCheckpointResponse,
+  normalizeCheckpointResponse,
+  proofContractFromAuthorCheckpointResponse,
+  statePathsForRunState
+});