@riddledc/riddle-proof 0.5.44 → 0.5.46

package/README.md

@@ -56,6 +56,23 @@ adapters are exposed through subpaths such as
 `@riddledc/riddle-proof/openclaw`, so wrappers can reuse the mapping logic
 without depending on another plugin runtime.
 
+## Durable Loop CLI
+
+The package publishes `riddle-proof-loop` as a host-agnostic runner surface for
+Codex/CLI-style testing:
+
+```sh
+riddle-proof-loop run --request-json request.json --checkpoint-mode yield
+riddle-proof-loop status --state-path /tmp/riddle-proof-run.json
+riddle-proof-loop respond --state-path /tmp/riddle-proof-run.json --response-json response.json
+riddle-proof-loop doctor codex_exec
+```
+
+In yield mode, the harness returns portable checkpoint packets for recon,
+authoring, implementation, proof assessment, and evidence recovery. A host can
+answer those packets with `riddle-proof.checkpoint_response.v1` JSON without
+needing OpenClaw-specific proof semantics.
+
 ## Runner Harness
 
 `runRiddleProof` is the reusable idea-to-PR workflow driver. It does not ship

package/dist/checkpoint.cjs

@@ -34,6 +34,9 @@ __export(checkpoint_exports, {
   RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION: () => RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION,
   authorPacketPayloadFromCheckpointResponse: () => authorPacketPayloadFromCheckpointResponse,
   buildAuthorCheckpointPacket: () => buildAuthorCheckpointPacket,
+  buildCheckpointPacketForEngineResult: () => buildCheckpointPacketForEngineResult,
+  buildProofAssessmentCheckpointPacket: () => buildProofAssessmentCheckpointPacket,
+  buildStageCheckpointPacket: () => buildStageCheckpointPacket,
   checkpointResponseIdentity: () => checkpointResponseIdentity,
   checkpointSummaryFromState: () => checkpointSummaryFromState,
   isDuplicateCheckpointResponse: () => isDuplicateCheckpointResponse,
@@ -131,6 +134,143 @@ function responseSchemaForAuthorPacket() {
     }
   };
 }
+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}`;
@@ -158,6 +298,106 @@ function artifactsFromState(state) {
   }
   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";
@@ -214,6 +454,129 @@ function buildAuthorCheckpointPacket(input) {
     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 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(input.request.verification_mode) || nonEmptyString(fullState.verification_mode) || nonEmptyString(bundle?.verification_mode) || "proof";
+  const visualDeltaRequired = 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: 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;
@@ -334,6 +697,9 @@ function proofContractFromAuthorCheckpointResponse(response, packet, payload) {
   RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION,
   authorPacketPayloadFromCheckpointResponse,
   buildAuthorCheckpointPacket,
+  buildCheckpointPacketForEngineResult,
+  buildProofAssessmentCheckpointPacket,
+  buildStageCheckpointPacket,
   checkpointResponseIdentity,
   checkpointSummaryFromState,
   isDuplicateCheckpointResponse,

package/dist/checkpoint.d.cts

@@ -3,6 +3,21 @@ import { RiddleProofCheckpointResponse, RiddleProofRunParams, RiddleProofRunStat
 declare const RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION: "riddle-proof.checkpoint.v1";
 declare const RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION: "riddle-proof.checkpoint_response.v1";
 declare function statePathsForRunState(state: RiddleProofRunState, engineStatePath?: string | null): RiddleProofStatePaths;
+declare function buildStageCheckpointPacket(input: {
+    request: RiddleProofRunParams;
+    runState: RiddleProofRunState;
+    engineResult: {
+        state_path?: string | null;
+        checkpoint?: string | null;
+        checkpointContract?: Record<string, unknown> | null;
+        decisionRequest?: Record<string, unknown> | null;
+        summary?: string;
+        stage?: string | null;
+    };
+    fullRiddleState?: Record<string, unknown> | null;
+    visibility?: "liveblog" | "quiet" | "terminal_only" | "manual" | string;
+    created_at?: string;
+}): RiddleProofCheckpointPacket;
 declare function buildAuthorCheckpointPacket(input: {
     request: RiddleProofRunParams;
     runState: RiddleProofRunState;
@@ -17,6 +32,34 @@ declare function buildAuthorCheckpointPacket(input: {
     visibility?: "liveblog" | "quiet" | "terminal_only" | "manual" | string;
     created_at?: string;
 }): RiddleProofCheckpointPacket;
+declare function buildProofAssessmentCheckpointPacket(input: {
+    request: RiddleProofRunParams;
+    runState: RiddleProofRunState;
+    engineResult: {
+        state_path?: string | null;
+        checkpoint?: string | null;
+        checkpointContract?: Record<string, unknown> | null;
+        decisionRequest?: Record<string, unknown> | null;
+        summary?: string;
+    };
+    fullRiddleState?: Record<string, unknown> | null;
+    visibility?: "liveblog" | "quiet" | "terminal_only" | "manual" | string;
+    created_at?: string;
+}): RiddleProofCheckpointPacket;
+declare function buildCheckpointPacketForEngineResult(input: {
+    request: RiddleProofRunParams;
+    runState: RiddleProofRunState;
+    engineResult: {
+        state_path?: string | null;
+        checkpoint?: string | null;
+        checkpointContract?: Record<string, unknown> | null;
+        decisionRequest?: Record<string, unknown> | null;
+        summary?: string;
+    };
+    fullRiddleState?: Record<string, unknown> | null;
+    visibility?: "liveblog" | "quiet" | "terminal_only" | "manual" | string;
+    created_at?: string;
+}): RiddleProofCheckpointPacket;
 declare function normalizeCheckpointResponse(value: unknown): RiddleProofCheckpointResponse | null;
 declare function checkpointSummaryFromState(state: RiddleProofRunState, engineStatePath?: string | null): RiddleProofCheckpointSummary;
 declare function isDuplicateCheckpointResponse(state: RiddleProofRunState, response: RiddleProofCheckpointResponse): boolean;
@@ -24,4 +67,4 @@ declare function checkpointResponseIdentity(response: RiddleProofCheckpointRespo
 declare function authorPacketPayloadFromCheckpointResponse(response: RiddleProofCheckpointResponse): Record<string, unknown> | null;
 declare function proofContractFromAuthorCheckpointResponse(response: RiddleProofCheckpointResponse, packet: RiddleProofCheckpointPacket, payload: Record<string, unknown>): RiddleProofProofContract;
 
-export { RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION, RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION, authorPacketPayloadFromCheckpointResponse, buildAuthorCheckpointPacket, checkpointResponseIdentity, checkpointSummaryFromState, isDuplicateCheckpointResponse, normalizeCheckpointResponse, proofContractFromAuthorCheckpointResponse, statePathsForRunState };
+export { RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION, RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION, authorPacketPayloadFromCheckpointResponse, buildAuthorCheckpointPacket, buildCheckpointPacketForEngineResult, buildProofAssessmentCheckpointPacket, buildStageCheckpointPacket, checkpointResponseIdentity, checkpointSummaryFromState, isDuplicateCheckpointResponse, normalizeCheckpointResponse, proofContractFromAuthorCheckpointResponse, statePathsForRunState };

package/dist/checkpoint.d.ts

@@ -3,6 +3,21 @@ import { RiddleProofCheckpointResponse, RiddleProofRunParams, RiddleProofRunStat
 declare const RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION: "riddle-proof.checkpoint.v1";
 declare const RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION: "riddle-proof.checkpoint_response.v1";
 declare function statePathsForRunState(state: RiddleProofRunState, engineStatePath?: string | null): RiddleProofStatePaths;
+declare function buildStageCheckpointPacket(input: {
+    request: RiddleProofRunParams;
+    runState: RiddleProofRunState;
+    engineResult: {
+        state_path?: string | null;
+        checkpoint?: string | null;
+        checkpointContract?: Record<string, unknown> | null;
+        decisionRequest?: Record<string, unknown> | null;
+        summary?: string;
+        stage?: string | null;
+    };
+    fullRiddleState?: Record<string, unknown> | null;
+    visibility?: "liveblog" | "quiet" | "terminal_only" | "manual" | string;
+    created_at?: string;
+}): RiddleProofCheckpointPacket;
 declare function buildAuthorCheckpointPacket(input: {
     request: RiddleProofRunParams;
     runState: RiddleProofRunState;
@@ -17,6 +32,34 @@ declare function buildAuthorCheckpointPacket(input: {
     visibility?: "liveblog" | "quiet" | "terminal_only" | "manual" | string;
     created_at?: string;
 }): RiddleProofCheckpointPacket;
+declare function buildProofAssessmentCheckpointPacket(input: {
+    request: RiddleProofRunParams;
+    runState: RiddleProofRunState;
+    engineResult: {
+        state_path?: string | null;
+        checkpoint?: string | null;
+        checkpointContract?: Record<string, unknown> | null;
+        decisionRequest?: Record<string, unknown> | null;
+        summary?: string;
+    };
+    fullRiddleState?: Record<string, unknown> | null;
+    visibility?: "liveblog" | "quiet" | "terminal_only" | "manual" | string;
+    created_at?: string;
+}): RiddleProofCheckpointPacket;
+declare function buildCheckpointPacketForEngineResult(input: {
+    request: RiddleProofRunParams;
+    runState: RiddleProofRunState;
+    engineResult: {
+        state_path?: string | null;
+        checkpoint?: string | null;
+        checkpointContract?: Record<string, unknown> | null;
+        decisionRequest?: Record<string, unknown> | null;
+        summary?: string;
+    };
+    fullRiddleState?: Record<string, unknown> | null;
+    visibility?: "liveblog" | "quiet" | "terminal_only" | "manual" | string;
+    created_at?: string;
+}): RiddleProofCheckpointPacket;
 declare function normalizeCheckpointResponse(value: unknown): RiddleProofCheckpointResponse | null;
 declare function checkpointSummaryFromState(state: RiddleProofRunState, engineStatePath?: string | null): RiddleProofCheckpointSummary;
 declare function isDuplicateCheckpointResponse(state: RiddleProofRunState, response: RiddleProofCheckpointResponse): boolean;
@@ -24,4 +67,4 @@ declare function checkpointResponseIdentity(response: RiddleProofCheckpointRespo
 declare function authorPacketPayloadFromCheckpointResponse(response: RiddleProofCheckpointResponse): Record<string, unknown> | null;
 declare function proofContractFromAuthorCheckpointResponse(response: RiddleProofCheckpointResponse, packet: RiddleProofCheckpointPacket, payload: Record<string, unknown>): RiddleProofProofContract;
 
-export { RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION, RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION, authorPacketPayloadFromCheckpointResponse, buildAuthorCheckpointPacket, checkpointResponseIdentity, checkpointSummaryFromState, isDuplicateCheckpointResponse, normalizeCheckpointResponse, proofContractFromAuthorCheckpointResponse, statePathsForRunState };
+export { RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION, RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION, authorPacketPayloadFromCheckpointResponse, buildAuthorCheckpointPacket, buildCheckpointPacketForEngineResult, buildProofAssessmentCheckpointPacket, buildStageCheckpointPacket, checkpointResponseIdentity, checkpointSummaryFromState, isDuplicateCheckpointResponse, normalizeCheckpointResponse, proofContractFromAuthorCheckpointResponse, statePathsForRunState };

package/dist/checkpoint.js

@@ -3,19 +3,25 @@ import {
   RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION,
   authorPacketPayloadFromCheckpointResponse,
   buildAuthorCheckpointPacket,
+  buildCheckpointPacketForEngineResult,
+  buildProofAssessmentCheckpointPacket,
+  buildStageCheckpointPacket,
   checkpointResponseIdentity,
   checkpointSummaryFromState,
   isDuplicateCheckpointResponse,
   normalizeCheckpointResponse,
   proofContractFromAuthorCheckpointResponse,
   statePathsForRunState
-} from "./chunk-RI25RGQP.js";
-import "./chunk-W7VTDN4T.js";
+} from "./chunk-R6SCWJCI.js";
+import "./chunk-DUFDZJOF.js";
 export {
   RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION,
   RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION,
   authorPacketPayloadFromCheckpointResponse,
   buildAuthorCheckpointPacket,
+  buildCheckpointPacketForEngineResult,
+  buildProofAssessmentCheckpointPacket,
+  buildStageCheckpointPacket,
   checkpointResponseIdentity,
   checkpointSummaryFromState,
   isDuplicateCheckpointResponse,

package/dist/{chunk-W7VTDN4T.js → chunk-DUFDZJOF.js}

@@ -206,6 +206,7 @@ function createRunResult(input) {
     checkpoint_summary: state.checkpoint_summary,
     state_paths: state.state_paths,
     proof_contract: state.proof_contract,
+    run_card: state.run_card,
     proof_session: state.proof_session,
     evidence_bundle: input.evidence_bundle,
     raw: input.raw

package/dist/{chunk-7S7O3NKF.js → chunk-JTNMEH57.js}

@@ -1,9 +1,12 @@
+import {
+  createRiddleProofRunCard
+} from "./chunk-PLSGW2GI.js";
 import {
   compactRecord,
   isTerminalStatus,
   nonEmptyString,
   recordValue
-} from "./chunk-W7VTDN4T.js";
+} from "./chunk-DUFDZJOF.js";
 
 // src/state.ts
 var RIDDLE_PROOF_RUN_STATE_VERSION = "riddle-proof.run-state.v1";
@@ -131,6 +134,7 @@ function createRunState(input) {
     checkpoint_summary: input.checkpoint_summary,
     state_paths: input.state_paths,
     proof_contract: input.proof_contract,
+    run_card: input.run_card,
     checkpoint_history: input.checkpoint_history,
     events: input.events ? [...input.events] : []
   });
@@ -209,6 +213,7 @@ function createRunStatusSnapshot(state, at = timestamp()) {
     checkpoint_summary: state.checkpoint_summary,
     state_paths: state.state_paths,
     proof_contract: state.proof_contract,
+    run_card: createRiddleProofRunCard(state, { at }),
     latest_event: latestEvent
   });
 }

package/dist/{chunk-MRSYJMF4.js → chunk-L26NTZOU.js}

@@ -3,10 +3,10 @@ import {
   appendStageHeartbeat,
   createRunState,
   setRunStatus
-} from "./chunk-7S7O3NKF.js";
+} from "./chunk-JTNMEH57.js";
 import {
   createRunResult
-} from "./chunk-W7VTDN4T.js";
+} from "./chunk-DUFDZJOF.js";
 
 // src/runner.ts
 function errorDetails(error) {