@riddledc/riddle-proof 0.5.37 → 0.5.39

package/dist/index.cjs

@@ -41,7 +41,7 @@ function currentDistDir() {
 }
 function createWorkflowStatePath() {
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[-:.TZ]/g, "").slice(0, 14);
-  return `/tmp/riddle-proof-state-${stamp}-${(0, import_node_crypto.randomUUID)().slice(0, 8)}.json`;
+  return `/tmp/riddle-proof-state-${stamp}-${(0, import_node_crypto2.randomUUID)().slice(0, 8)}.json`;
 }
 function argsPathForStatePath(statePath) {
   const base = import_node_path.default.basename(statePath);
@@ -759,12 +759,12 @@ function summarizeState(state) {
     state: selected
   };
 }
-var import_node_fs, import_node_crypto, import_node_path, import_node_url, import_meta, WORKFLOW_STAGE_ORDER, CHECKPOINT_CONTRACT_VERSION, BUNDLED_RIDDLE_PROOF_DIR, RIDDLE_PROOF_DIR_CANDIDATES, VISUAL_FIRST_MODES, CHECKPOINT_CONTRACT_SPECS;
+var import_node_fs, import_node_crypto2, import_node_path, import_node_url, import_meta, WORKFLOW_STAGE_ORDER, CHECKPOINT_CONTRACT_VERSION, BUNDLED_RIDDLE_PROOF_DIR, RIDDLE_PROOF_DIR_CANDIDATES, VISUAL_FIRST_MODES, CHECKPOINT_CONTRACT_SPECS;
 var init_proof_run_core = __esm({
   "src/proof-run-core.ts"() {
     "use strict";
     import_node_fs = require("fs");
-    import_node_crypto = require("crypto");
+    import_node_crypto2 = require("crypto");
     import_node_path = __toESM(require("path"), 1);
     import_node_url = require("url");
     import_meta = {};
@@ -2735,6 +2735,8 @@ __export(index_exports, {
   DEFAULT_DIAGNOSTIC_HISTORY_LIMIT: () => DEFAULT_DIAGNOSTIC_HISTORY_LIMIT,
   DEFAULT_DIAGNOSTIC_STRING_LIMIT: () => DEFAULT_DIAGNOSTIC_STRING_LIMIT,
   RIDDLE_PROOF_CAPTURE_DIAGNOSTIC_VERSION: () => RIDDLE_PROOF_CAPTURE_DIAGNOSTIC_VERSION,
+  RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION: () => RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION,
+  RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION: () => RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION,
   RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION: () => RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION,
   RIDDLE_PROOF_PLAYABILITY_VERSION: () => RIDDLE_PROOF_PLAYABILITY_VERSION,
   RIDDLE_PROOF_RUN_STATE_VERSION: () => RIDDLE_PROOF_RUN_STATE_VERSION,
@@ -2746,6 +2748,8 @@ __export(index_exports, {
   applyPrLifecycleState: () => applyPrLifecycleState,
   applyTerminalMetadata: () => applyTerminalMetadata,
   assessPlayabilityEvidence: () => assessPlayabilityEvidence,
+  authorPacketPayloadFromCheckpointResponse: () => authorPacketPayloadFromCheckpointResponse,
+  buildAuthorCheckpointPacket: () => buildAuthorCheckpointPacket,
   buildVisualProofSession: () => buildVisualProofSession,
   compactRecord: () => compactRecord,
   compareVisualProofSessionFingerprint: () => compareVisualProofSessionFingerprint,
@@ -2759,6 +2763,7 @@ __export(index_exports, {
   isSuccessfulStatus: () => isSuccessfulStatus,
   isTerminalStatus: () => isTerminalStatus,
   nonEmptyString: () => nonEmptyString,
+  normalizeCheckpointResponse: () => normalizeCheckpointResponse,
   normalizeIntegrationContext: () => normalizeIntegrationContext,
   normalizePrLifecycleState: () => normalizePrLifecycleState,
   normalizeRunParams: () => normalizeRunParams,
@@ -2980,6 +2985,7 @@ function createRunResult(input) {
     merge_recommendation: state.merge_recommendation,
     finalized: state.finalized,
     blocker: state.blocker,
+    checkpoint_packet: state.checkpoint_packet,
     proof_session: state.proof_session,
     evidence_bundle: input.evidence_bundle,
     raw: input.raw
@@ -3108,6 +3114,8 @@ function createRunState(input) {
     request: normalizeRunParams(input.request),
     iterations: input.iterations ?? 0,
     last_checkpoint: input.last_checkpoint ?? null,
+    checkpoint_packet: input.checkpoint_packet,
+    checkpoint_history: input.checkpoint_history,
     events: input.events ? [...input.events] : []
   });
 }
@@ -3181,6 +3189,7 @@ function createRunStatusSnapshot(state, at = timestamp()) {
     elapsed_ms: elapsedMs(state.created_at, at),
     stage_elapsed_ms: elapsedMs(state.stage_started_at, at),
     blocker: state.blocker,
+    checkpoint_packet: state.checkpoint_packet,
     latest_event: latestEvent
   });
 }
@@ -3208,6 +3217,178 @@ function applyPrLifecycleState(state, input, at = timestamp()) {
   return state;
 }
 
+// src/checkpoint.ts
+var import_node_crypto = __toESM(require("crypto"), 1);
+var RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION = "riddle-proof.checkpoint.v1";
+var RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION = "riddle-proof.checkpoint_response.v1";
+function timestamp2() {
+  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 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 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 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 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 || timestamp2()
+  };
+}
+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) || timestamp2()
+  });
+}
+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;
+}
+
 // src/runner.ts
 function errorDetails(error) {
   if (error instanceof Error) {
@@ -3694,7 +3875,7 @@ async function runRiddleProof(input) {
 var import_node_child_process2 = require("child_process");
 var import_node_fs3 = require("fs");
 var import_node_path3 = __toESM(require("path"), 1);
-var import_node_crypto2 = __toESM(require("crypto"), 1);
+var import_node_crypto3 = __toESM(require("crypto"), 1);
 init_proof_run_core();
 var DEFAULT_MAX_ITERATIONS = 12;
 var DEFAULT_STAGE_ITERATION_LIMITS = {
@@ -3707,12 +3888,12 @@ var DEFAULT_STAGE_ITERATION_LIMITS = {
   ship: 2,
   notify: 2
 };
-function timestamp2() {
+function timestamp3() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
 function createHarnessStatePath(stateDir) {
-  const stamp = timestamp2().replace(/\D/g, "").slice(0, 14) || "unknown";
-  return import_node_path3.default.join(stateDir, `riddle-proof-run-${stamp}-${import_node_crypto2.default.randomUUID().slice(0, 8)}.json`);
+  const stamp = timestamp3().replace(/\D/g, "").slice(0, 14) || "unknown";
+  return import_node_path3.default.join(stateDir, `riddle-proof-run-${stamp}-${import_node_crypto3.default.randomUUID().slice(0, 8)}.json`);
 }
 function createEngineStatePath(state, config) {
   const existing = nonEmptyString(state.request.engine_state_path);
@@ -3727,8 +3908,8 @@ function createEngineStatePath(state, config) {
     return import_node_path3.default.join(dir, `${base}.engine-state.json`);
   }
   const stateDir = config?.stateDir || "/tmp";
-  const stamp = timestamp2().replace(/\D/g, "").slice(0, 14) || "unknown";
-  return import_node_path3.default.join(stateDir, `riddle-proof-state-${stamp}-${import_node_crypto2.default.randomUUID().slice(0, 8)}.json`);
+  const stamp = timestamp3().replace(/\D/g, "").slice(0, 14) || "unknown";
+  return import_node_path3.default.join(stateDir, `riddle-proof-state-${stamp}-${import_node_crypto3.default.randomUUID().slice(0, 8)}.json`);
 }
 function ensureParent(filePath) {
   (0, import_node_fs3.mkdirSync)(import_node_path3.default.dirname(filePath), { recursive: true });
@@ -4069,6 +4250,150 @@ function blockerResult(state, result, blocker) {
     }
   });
 }
+function checkpointAwaitingResult(state, result, visibility) {
+  const packet = buildAuthorCheckpointPacket({
+    request: state.request,
+    runState: state,
+    engineResult: result,
+    fullRiddleState: fullRiddleState(result, state),
+    visibility
+  });
+  const at = timestamp3();
+  state.checkpoint_packet = packet;
+  state.checkpoint_history = [
+    ...state.checkpoint_history || [],
+    { ts: at, packet }
+  ].slice(-25);
+  appendRunEvent(state, {
+    ts: at,
+    kind: "checkpoint.packet.created",
+    checkpoint: packet.checkpoint,
+    stage: packet.stage,
+    summary: packet.summary,
+    details: compactRecord({
+      kind: packet.kind,
+      routing_hint: packet.routing_hint,
+      resume_token: packet.resume_token
+    })
+  });
+  setRunStatus(state, "awaiting_checkpoint", at);
+  persist(state);
+  return createRunResult({
+    state,
+    status: "awaiting_checkpoint",
+    last_summary: packet.summary,
+    raw: {
+      engine_state_path: result.state_path || state.request.engine_state_path || null,
+      last_result: result,
+      checkpoint_packet: packet
+    }
+  });
+}
+function appendCheckpointResponse(state, response, input = {}) {
+  const at = timestamp3();
+  state.checkpoint_history = [
+    ...state.checkpoint_history || [],
+    { ts: at, response }
+  ].slice(-25);
+  if (input.clear_packet !== false) {
+    state.checkpoint_packet = void 0;
+  }
+  appendRunEvent(state, {
+    ts: at,
+    kind: "checkpoint.response.accepted",
+    checkpoint: response.checkpoint,
+    stage: state.current_stage || "author",
+    summary: input.summary || response.summary,
+    details: compactRecord({
+      decision: response.decision,
+      resume_token: response.resume_token,
+      source: response.source
+    })
+  });
+  setRunStatus(state, "running", at);
+  persist(state);
+}
+function checkpointResponseContinuation(state, value) {
+  if (!value) return {};
+  const packet = state.checkpoint_packet;
+  const response = normalizeCheckpointResponse(value);
+  if (!response) {
+    return {
+      blocker: {
+        code: "checkpoint_response_invalid",
+        checkpoint: packet?.checkpoint || state.last_checkpoint || null,
+        message: "Checkpoint response was not a valid riddle-proof.checkpoint_response.v1 object.",
+        details: { checkpoint_packet: packet || null }
+      }
+    };
+  }
+  if (!packet) {
+    return {
+      blocker: {
+        code: "checkpoint_response_without_packet",
+        checkpoint: response.checkpoint,
+        message: "A checkpoint response was supplied, but the run state has no pending checkpoint packet.",
+        details: { response }
+      }
+    };
+  }
+  if (response.run_id !== packet.run_id || response.checkpoint !== packet.checkpoint) {
+    return {
+      blocker: {
+        code: "checkpoint_response_mismatch",
+        checkpoint: packet.checkpoint,
+        message: "Checkpoint response does not match the pending checkpoint packet.",
+        details: {
+          expected: { run_id: packet.run_id, checkpoint: packet.checkpoint },
+          actual: { run_id: response.run_id, checkpoint: response.checkpoint }
+        }
+      }
+    };
+  }
+  if (packet.resume_token && response.resume_token !== packet.resume_token) {
+    return {
+      blocker: {
+        code: "checkpoint_response_resume_token_mismatch",
+        checkpoint: packet.checkpoint,
+        message: "Checkpoint response resume_token does not match the pending checkpoint packet.",
+        details: { expected_resume_token: packet.resume_token, actual_resume_token: response.resume_token || null }
+      }
+    };
+  }
+  const base = {
+    action: "run",
+    state_path: state.request.engine_state_path || packet.state_path || "",
+    continue_from_checkpoint: true
+  };
+  if (response.decision === "author_packet") {
+    const payload = authorPacketPayloadFromCheckpointResponse(response);
+    if (!payload) {
+      return {
+        blocker: {
+          code: "checkpoint_author_packet_missing",
+          checkpoint: packet.checkpoint,
+          message: "Checkpoint response decision=author_packet did not include a proof_plan and capture_script payload.",
+          details: { response }
+        }
+      };
+    }
+    appendCheckpointResponse(state, response);
+    return { next: { ...base, author_packet_json: jsonParam(payload) } };
+  }
+  if (response.decision === "needs_recon") {
+    appendCheckpointResponse(state, response);
+    return { next: { ...base, advance_stage: "recon" } };
+  }
+  appendCheckpointResponse(state, response, { clear_packet: false });
+  return {
+    blocker: {
+      code: `checkpoint_response_${response.decision}`,
+      checkpoint: packet.checkpoint,
+      message: response.summary || `Checkpoint response stopped the run with decision=${response.decision}.`,
+      details: { response }
+    }
+  };
+}
 function disabledAdapterPayload(action, context) {
   return {
     ok: false,
@@ -4317,6 +4642,9 @@ async function routeCheckpoint(request, state, result, agent, input) {
   const continueStage = checkpointContinueStage2(result);
   const checkpointContinuesToAuthor = continueStage === "author";
   if (checkpoint === "author_supervisor_judgment" || checkpoint === "verify_capture_retry" || checkpoint === "verify_agent_retry" && checkpointContinuesToAuthor) {
+    if (input.checkpoint_mode === "yield") {
+      return { terminal: checkpointAwaitingResult(state, result, input.checkpoint_visibility) };
+    }
     const packet = await agent.authorProofPacket(context);
     const blocker = requirePayload("author_packet", packet, state, result);
     if (blocker) return { blocker };
@@ -4418,6 +4746,10 @@ async function runRiddleProofEngineHarness(input) {
   const state = loadRunState(input);
   state.request = normalizeRunParams({ ...state.request, ...input.request });
   state.request.engine_state_path = nonEmptyString(input.resume_params?.state_path) || nonEmptyString(state.request.engine_state_path) || createEngineStatePath(state, input.config);
+  const checkpointContinuation = checkpointResponseContinuation(state, input.checkpoint_response);
+  if (checkpointContinuation.blocker) {
+    return blockerResult(state, null, checkpointContinuation.blocker);
+  }
   const request = state.request;
   const agent = input.agent || createDisabledRiddleProofAgentAdapter();
   const maxIterations = Math.max(
@@ -4439,6 +4771,8 @@ async function runRiddleProofEngineHarness(input) {
       engine_state_path: request.engine_state_path || null,
       max_iterations: maxIterations,
       ship_mode: effectiveShipMode(request, input.config),
+      checkpoint_mode: input.checkpoint_mode || "auto",
+      checkpoint_visibility: input.checkpoint_visibility || null,
       leave_draft: request.leave_draft || false
     }
   });
@@ -4453,7 +4787,7 @@ async function runRiddleProofEngineHarness(input) {
       message
     });
   }
-  let nextParams = input.resume_params || initialRunParams(request, input, state);
+  let nextParams = input.resume_params || checkpointContinuation.next || initialRunParams(request, input, state);
   let lastResult = null;
   const stageIterations = {};
   for (let index = 0; index < maxIterations; index += 1) {
@@ -4474,7 +4808,7 @@ async function runRiddleProofEngineHarness(input) {
         branch: state.branch || null
       }
     });
-    const engineCallStartedAt = timestamp2();
+    const engineCallStartedAt = timestamp3();
     const engineCallStartedMs = Date.now();
     recordEvent(state, {
       kind: "engine.call",
@@ -4499,7 +4833,7 @@ async function runRiddleProofEngineHarness(input) {
         details: {
           duration_ms: Date.now() - engineCallStartedMs,
           started_at: engineCallStartedAt,
-          finished_at: timestamp2()
+          finished_at: timestamp3()
         }
       });
       return blockerResult(state, lastResult, {
@@ -4537,7 +4871,7 @@ async function runRiddleProofEngineHarness(input) {
         checkpoint: result.checkpoint || null,
         duration_ms: engineCallDurationMs,
         started_at: engineCallStartedAt,
-        finished_at: timestamp2()
+        finished_at: timestamp3()
       }
     });
     const stageLimit = DEFAULT_STAGE_ITERATION_LIMITS[resultStage];
@@ -4721,7 +5055,7 @@ function appendCaptureDiagnostic(state, input, historyLimit = DEFAULT_DIAGNOSTIC
 }
 
 // src/proof-session.ts
-var import_node_crypto3 = require("crypto");
+var import_node_crypto4 = require("crypto");
 var RIDDLE_PROOF_VISUAL_SESSION_VERSION = "riddle-proof.visual-session.v1";
 var RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_VERSION = "riddle-proof.visual-session.fingerprint.v1";
 function trim(value) {
@@ -4731,7 +5065,7 @@ function trim(value) {
 function hashString(value) {
   const text = trim(value);
   if (!text) return void 0;
-  return (0, import_node_crypto3.createHash)("sha256").update(text).digest("hex");
+  return (0, import_node_crypto4.createHash)("sha256").update(text).digest("hex");
 }
 function stableJson(value) {
   if (value === void 0) return "null";
@@ -4764,14 +5098,14 @@ function visualSessionFingerprintBasis(input) {
 }
 function visualSessionFingerprint(input) {
   const basis = input.version === RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_VERSION ? input : visualSessionFingerprintBasis(input);
-  return (0, import_node_crypto3.createHash)("sha256").update(stableJson(basis)).digest("hex");
+  return (0, import_node_crypto4.createHash)("sha256").update(stableJson(basis)).digest("hex");
 }
 function buildVisualProofSession(input) {
   const basis = visualSessionFingerprintBasis(input);
   const fingerprint = visualSessionFingerprint(basis);
   const session = {
     version: RIDDLE_PROOF_VISUAL_SESSION_VERSION,
-    session_id: `rps_${(/* @__PURE__ */ new Date()).toISOString().replace(/[-:.TZ]/g, "").slice(0, 14)}_${(0, import_node_crypto3.randomUUID)().slice(0, 8)}`,
+    session_id: `rps_${(/* @__PURE__ */ new Date()).toISOString().replace(/[-:.TZ]/g, "").slice(0, 14)}_${(0, import_node_crypto4.randomUUID)().slice(0, 8)}`,
     run_id: trim(input.run_id),
     parent_session_id: input.parent?.session_id || null,
     parent_fingerprint: input.parent?.fingerprint || null,
@@ -5191,6 +5525,8 @@ function parseJson(value) {
   DEFAULT_DIAGNOSTIC_HISTORY_LIMIT,
   DEFAULT_DIAGNOSTIC_STRING_LIMIT,
   RIDDLE_PROOF_CAPTURE_DIAGNOSTIC_VERSION,
+  RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION,
+  RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION,
   RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION,
   RIDDLE_PROOF_PLAYABILITY_VERSION,
   RIDDLE_PROOF_RUN_STATE_VERSION,
@@ -5202,6 +5538,8 @@ function parseJson(value) {
   applyPrLifecycleState,
   applyTerminalMetadata,
   assessPlayabilityEvidence,
+  authorPacketPayloadFromCheckpointResponse,
+  buildAuthorCheckpointPacket,
   buildVisualProofSession,
   compactRecord,
   compareVisualProofSessionFingerprint,
@@ -5215,6 +5553,7 @@ function parseJson(value) {
   isSuccessfulStatus,
   isTerminalStatus,
   nonEmptyString,
+  normalizeCheckpointResponse,
   normalizeIntegrationContext,
   normalizePrLifecycleState,
   normalizeRunParams,

package/dist/index.d.cts

@@ -1,8 +1,9 @@
-export { EvidenceArtifact, EvidenceReference, ImplementationAdapter, ImplementationAdapterInput, ImplementationAdapterResult, IntegrationContext, JsonObject, JsonPrimitive, JsonValue, JudgeAdapter, NotificationAdapter, PreflightAdapter, PreflightAdapterInput, PreflightAdapterResult, ProofAdapter, ProofAdapterInput, ProofAdapterResult, RiddleProofArtifactRole, RiddleProofAssessment, RiddleProofBlocker, RiddleProofDecision, RiddleProofEvent, RiddleProofEvidenceBundle, RiddleProofPrLifecycleState, RiddleProofPrLifecycleStatus, RiddleProofRunParams, RiddleProofRunResult, RiddleProofRunState, RiddleProofRunStatusSnapshot, RiddleProofStage, RiddleProofStatus, RiddleProofTerminalMetadata, RiddleProofVerificationMode, RiddleProofVisualSession, RiddleProofVisualSessionFingerprintBasis, SetupAdapter, SetupAdapterInput, SetupAdapterResult, ShipAdapter } from './types.cjs';
+export { EvidenceArtifact, EvidenceReference, ImplementationAdapter, ImplementationAdapterInput, ImplementationAdapterResult, IntegrationContext, JsonObject, JsonPrimitive, JsonValue, JudgeAdapter, NotificationAdapter, PreflightAdapter, PreflightAdapterInput, PreflightAdapterResult, ProofAdapter, ProofAdapterInput, ProofAdapterResult, RiddleProofArtifactRole, RiddleProofAssessment, RiddleProofBlocker, RiddleProofCheckpointArtifact, RiddleProofCheckpointPacket, RiddleProofCheckpointResponse, RiddleProofCheckpointRole, RiddleProofCheckpointRoutingHint, RiddleProofCheckpointVisibility, RiddleProofDecision, RiddleProofEvent, RiddleProofEvidenceBundle, RiddleProofPrLifecycleState, RiddleProofPrLifecycleStatus, RiddleProofRunParams, RiddleProofRunResult, RiddleProofRunState, RiddleProofRunStatusSnapshot, RiddleProofStage, RiddleProofStatus, RiddleProofTerminalMetadata, RiddleProofVerificationMode, RiddleProofVisualSession, RiddleProofVisualSessionFingerprintBasis, SetupAdapter, SetupAdapterInput, SetupAdapterResult, ShipAdapter } from './types.cjs';
 export { TerminalMetadataInput, applyTerminalMetadata, compactRecord, createRunResult, isSuccessfulStatus, isTerminalStatus, nonEmptyString, normalizeTerminalMetadata, recordValue } from './result.cjs';
 export { CreateRunStateInput, RIDDLE_PROOF_RUN_STATE_VERSION, RunEventInput, appendRunEvent, appendStageHeartbeat, applyPrLifecycleState, createRunState, createRunStatusSnapshot, normalizeIntegrationContext, normalizePrLifecycleState, normalizeRunParams, setRunStatus } from './state.cjs';
+export { RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION, RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION, authorPacketPayloadFromCheckpointResponse, buildAuthorCheckpointPacket, normalizeCheckpointResponse } from './checkpoint.cjs';
 export { RiddleProofRunnerAdapters, RunRiddleProofInput, runRiddleProof } from './runner.cjs';
-export { RiddleProofAgentAdapter, RiddleProofAgentPayload, RiddleProofEngine, RiddleProofEngineHarnessConfig, RiddleProofEngineHarnessContext, RiddleProofEngineResult, RiddleProofShipMode, RiddleProofWorkflowParams, RunRiddleProofEngineHarnessInput, createDisabledRiddleProofAgentAdapter, readRiddleProofRunStatus, runRiddleProofEngineHarness } from './engine-harness.cjs';
+export { RiddleProofAgentAdapter, RiddleProofAgentPayload, RiddleProofCheckpointMode, RiddleProofEngine, RiddleProofEngineHarnessConfig, RiddleProofEngineHarnessContext, RiddleProofEngineResult, RiddleProofShipMode, RiddleProofWorkflowParams, RunRiddleProofEngineHarnessInput, createDisabledRiddleProofAgentAdapter, readRiddleProofRunStatus, runRiddleProofEngineHarness } from './engine-harness.cjs';
 export { CreateCaptureDiagnosticInput, DEFAULT_DIAGNOSTIC_ARRAY_LIMIT, DEFAULT_DIAGNOSTIC_HISTORY_LIMIT, DEFAULT_DIAGNOSTIC_STRING_LIMIT, RIDDLE_PROOF_CAPTURE_DIAGNOSTIC_VERSION, RiddleProofArtifactSummary, RiddleProofCaptureArtifactSummary, RiddleProofCaptureDiagnostic, RiddleProofDiagnosticRedactionOptions, appendCaptureDiagnostic, createCaptureDiagnostic, redactForProofDiagnostics, summarizeCaptureArtifacts } from './diagnostics.cjs';
 export { BuildVisualProofSessionInput, RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_VERSION, RIDDLE_PROOF_VISUAL_SESSION_VERSION, VisualProofSessionMismatch, buildVisualProofSession, compareVisualProofSessionFingerprint, parseVisualProofSession, visualSessionFingerprint, visualSessionFingerprintBasis } from './proof-session.cjs';
 export { AssessPlayabilityOptions, RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION, RIDDLE_PROOF_PLAYABILITY_VERSION, RiddleProofPlayabilityAssessment, RiddleProofPlayabilityEvidence, assessPlayabilityEvidence, extractPlayabilityEvidence, isRiddleProofPlayabilityMode } from './playability.cjs';

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-export { EvidenceArtifact, EvidenceReference, ImplementationAdapter, ImplementationAdapterInput, ImplementationAdapterResult, IntegrationContext, JsonObject, JsonPrimitive, JsonValue, JudgeAdapter, NotificationAdapter, PreflightAdapter, PreflightAdapterInput, PreflightAdapterResult, ProofAdapter, ProofAdapterInput, ProofAdapterResult, RiddleProofArtifactRole, RiddleProofAssessment, RiddleProofBlocker, RiddleProofDecision, RiddleProofEvent, RiddleProofEvidenceBundle, RiddleProofPrLifecycleState, RiddleProofPrLifecycleStatus, RiddleProofRunParams, RiddleProofRunResult, RiddleProofRunState, RiddleProofRunStatusSnapshot, RiddleProofStage, RiddleProofStatus, RiddleProofTerminalMetadata, RiddleProofVerificationMode, RiddleProofVisualSession, RiddleProofVisualSessionFingerprintBasis, SetupAdapter, SetupAdapterInput, SetupAdapterResult, ShipAdapter } from './types.js';
+export { EvidenceArtifact, EvidenceReference, ImplementationAdapter, ImplementationAdapterInput, ImplementationAdapterResult, IntegrationContext, JsonObject, JsonPrimitive, JsonValue, JudgeAdapter, NotificationAdapter, PreflightAdapter, PreflightAdapterInput, PreflightAdapterResult, ProofAdapter, ProofAdapterInput, ProofAdapterResult, RiddleProofArtifactRole, RiddleProofAssessment, RiddleProofBlocker, RiddleProofCheckpointArtifact, RiddleProofCheckpointPacket, RiddleProofCheckpointResponse, RiddleProofCheckpointRole, RiddleProofCheckpointRoutingHint, RiddleProofCheckpointVisibility, RiddleProofDecision, RiddleProofEvent, RiddleProofEvidenceBundle, RiddleProofPrLifecycleState, RiddleProofPrLifecycleStatus, RiddleProofRunParams, RiddleProofRunResult, RiddleProofRunState, RiddleProofRunStatusSnapshot, RiddleProofStage, RiddleProofStatus, RiddleProofTerminalMetadata, RiddleProofVerificationMode, RiddleProofVisualSession, RiddleProofVisualSessionFingerprintBasis, SetupAdapter, SetupAdapterInput, SetupAdapterResult, ShipAdapter } from './types.js';
 export { TerminalMetadataInput, applyTerminalMetadata, compactRecord, createRunResult, isSuccessfulStatus, isTerminalStatus, nonEmptyString, normalizeTerminalMetadata, recordValue } from './result.js';
 export { CreateRunStateInput, RIDDLE_PROOF_RUN_STATE_VERSION, RunEventInput, appendRunEvent, appendStageHeartbeat, applyPrLifecycleState, createRunState, createRunStatusSnapshot, normalizeIntegrationContext, normalizePrLifecycleState, normalizeRunParams, setRunStatus } from './state.js';
+export { RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION, RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION, authorPacketPayloadFromCheckpointResponse, buildAuthorCheckpointPacket, normalizeCheckpointResponse } from './checkpoint.js';
 export { RiddleProofRunnerAdapters, RunRiddleProofInput, runRiddleProof } from './runner.js';
-export { RiddleProofAgentAdapter, RiddleProofAgentPayload, RiddleProofEngine, RiddleProofEngineHarnessConfig, RiddleProofEngineHarnessContext, RiddleProofEngineResult, RiddleProofShipMode, RiddleProofWorkflowParams, RunRiddleProofEngineHarnessInput, createDisabledRiddleProofAgentAdapter, readRiddleProofRunStatus, runRiddleProofEngineHarness } from './engine-harness.js';
+export { RiddleProofAgentAdapter, RiddleProofAgentPayload, RiddleProofCheckpointMode, RiddleProofEngine, RiddleProofEngineHarnessConfig, RiddleProofEngineHarnessContext, RiddleProofEngineResult, RiddleProofShipMode, RiddleProofWorkflowParams, RunRiddleProofEngineHarnessInput, createDisabledRiddleProofAgentAdapter, readRiddleProofRunStatus, runRiddleProofEngineHarness } from './engine-harness.js';
 export { CreateCaptureDiagnosticInput, DEFAULT_DIAGNOSTIC_ARRAY_LIMIT, DEFAULT_DIAGNOSTIC_HISTORY_LIMIT, DEFAULT_DIAGNOSTIC_STRING_LIMIT, RIDDLE_PROOF_CAPTURE_DIAGNOSTIC_VERSION, RiddleProofArtifactSummary, RiddleProofCaptureArtifactSummary, RiddleProofCaptureDiagnostic, RiddleProofDiagnosticRedactionOptions, appendCaptureDiagnostic, createCaptureDiagnostic, redactForProofDiagnostics, summarizeCaptureArtifacts } from './diagnostics.js';
 export { BuildVisualProofSessionInput, RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_VERSION, RIDDLE_PROOF_VISUAL_SESSION_VERSION, VisualProofSessionMismatch, buildVisualProofSession, compareVisualProofSessionFingerprint, parseVisualProofSession, visualSessionFingerprint, visualSessionFingerprintBasis } from './proof-session.js';
 export { AssessPlayabilityOptions, RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION, RIDDLE_PROOF_PLAYABILITY_VERSION, RiddleProofPlayabilityAssessment, RiddleProofPlayabilityEvidence, assessPlayabilityEvidence, extractPlayabilityEvidence, isRiddleProofPlayabilityMode } from './playability.js';