@riddledc/riddle-proof 0.2.0 → 0.3.0

package/dist/runner.cjs

@@ -59,7 +59,11 @@ function createRunResult(input) {
   return compactRecord({
     ok,
     status,
+    run_id: state.run_id,
     state_path: input.state_path ?? state.state_path ?? null,
+    worktree_path: state.worktree_path ?? null,
+    branch: state.branch ?? null,
+    current_stage: state.current_stage ?? null,
     iterations: state.iterations,
     last_checkpoint: state.last_checkpoint ?? null,
     last_summary: input.last_summary ?? null,
@@ -81,6 +85,17 @@ var RIDDLE_PROOF_RUN_STATE_VERSION = "riddle-proof.run-state.v1";
 function timestamp() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
+function createRunId(createdAt) {
+  const stamp = createdAt.replace(/\D/g, "").slice(0, 14) || "unknown";
+  const entropy = Math.random().toString(36).slice(2, 8) || "run";
+  return `rp_${stamp}_${entropy}`;
+}
+function elapsedMs(start, end) {
+  const startMs = start ? Date.parse(start) : NaN;
+  const endMs = end ? Date.parse(end) : NaN;
+  if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) return void 0;
+  return Math.max(0, endMs - startMs);
+}
 function normalizeIntegrationContext(input, fallbackSource) {
   const value = recordValue(input);
   if (!value) {
@@ -131,7 +146,12 @@ function createRunState(input) {
   const createdAt = input.created_at || timestamp();
   return compactRecord({
     version: RIDDLE_PROOF_RUN_STATE_VERSION,
+    run_id: input.run_id || createRunId(createdAt),
     state_path: input.state_path,
+    worktree_path: input.worktree_path,
+    branch: input.branch || input.request.branch,
+    current_stage: input.current_stage ?? null,
+    stage_started_at: input.stage_started_at ?? null,
     status: input.status || "running",
     created_at: createdAt,
     updated_at: input.updated_at || createdAt,
@@ -159,9 +179,30 @@ function appendRunEvent(state, input) {
     details: event.details
   }));
   if (input.checkpoint !== void 0) state.last_checkpoint = input.checkpoint;
+  if (input.stage !== void 0) {
+    if (state.current_stage !== input.stage) state.stage_started_at = event.ts;
+    state.current_stage = input.stage;
+  }
   state.updated_at = event.ts;
   return state;
 }
+function appendStageHeartbeat(state, input) {
+  const at = input.ts || timestamp();
+  return appendRunEvent(state, {
+    ts: at,
+    kind: "stage.heartbeat",
+    checkpoint: input.checkpoint || `${input.stage}_heartbeat`,
+    stage: input.stage,
+    summary: input.summary || `${input.stage} stage is active.`,
+    details: compactRecord({
+      elapsed_ms: elapsedMs(state.created_at, at),
+      stage_elapsed_ms: elapsedMs(state.stage_started_at, at),
+      wait_reason: input.wait_reason,
+      blocker: input.blocker,
+      ...input.details
+    })
+  });
+}
 function setRunStatus(state, status, at = timestamp()) {
   state.status = status;
   state.ok = status !== "blocked" && status !== "failed";
@@ -246,7 +287,8 @@ async function notifyIfConfigured(input) {
 async function runRiddleProof(input) {
   const state = input.state || createRunState({
     request: input.request,
-    state_path: input.state_path
+    state_path: input.state_path,
+    worktree_path: input.workdir
   });
   const adapters = input.adapters || {};
   const maxIterations = Math.max(1, Math.trunc(input.max_iterations ?? 1));
@@ -256,12 +298,70 @@ async function runRiddleProof(input) {
     stage: "setup",
     summary: "Riddle Proof run started.",
     details: {
+      run_id: state.run_id,
+      state_path: state.state_path,
+      worktree_path: state.worktree_path,
+      branch: state.branch,
       max_iterations: maxIterations,
       ship_mode: state.request.ship_mode || "none"
     }
   });
+  appendStageHeartbeat(state, {
+    stage: "setup",
+    summary: "Setup stage is active.",
+    details: {
+      run_id: state.run_id,
+      state_path: state.state_path,
+      worktree_path: state.worktree_path,
+      branch: state.branch
+    }
+  });
   let workdir = input.workdir;
   let evidenceContext;
+  if (adapters.preflight) {
+    appendRunEvent(state, {
+      kind: "preflight.started",
+      checkpoint: "preflight_started",
+      stage: "preflight",
+      summary: "Riddle Proof preflight adapter started."
+    });
+    try {
+      const preflight = await adapters.preflight.preflight({ request: state.request, state });
+      if (!preflight.ok) {
+        return blockRun({
+          state,
+          stage: "preflight",
+          blocker: adapterBlocker(
+            "preflight_failed",
+            "The preflight adapter found blocking tool or model configuration issues.",
+            "preflight_failed",
+            {
+              blockers: preflight.blockers,
+              warnings: preflight.warnings,
+              degraded_capabilities: preflight.degraded_capabilities
+            }
+          ),
+          raw: { preflight }
+        });
+      }
+      appendRunEvent(state, {
+        kind: "preflight.completed",
+        checkpoint: "preflight_completed",
+        stage: "preflight",
+        summary: "Riddle Proof preflight adapter completed.",
+        details: {
+          warnings: preflight.warnings,
+          degraded_capabilities: preflight.degraded_capabilities
+        }
+      });
+    } catch (error) {
+      return blockRun({
+        state,
+        stage: "preflight",
+        blocker: adapterBlocker("preflight_exception", "The preflight adapter threw an exception.", "preflight_failed", errorDetails(error))
+      });
+    }
+  }
   if (adapters.setup) {
     appendRunEvent(state, {
       kind: "setup.started",
@@ -284,7 +384,9 @@ async function runRiddleProof(input) {
           raw: { setup }
         });
       }
-      workdir = setup.workdir || workdir;
+      workdir = setup.worktree_path || setup.workdir || workdir;
+      state.worktree_path = setup.worktree_path || setup.workdir || state.worktree_path;
+      state.branch = setup.branch || state.branch;
       evidenceContext = setup.evidence_context;
       appendRunEvent(state, {
         kind: "setup.completed",
@@ -293,6 +395,9 @@ async function runRiddleProof(input) {
         summary: "Riddle Proof setup adapter completed.",
         details: {
           has_workdir: Boolean(workdir),
+          worktree_path: state.worktree_path,
+          branch: state.branch,
+          cleanup_policy: setup.cleanup_policy,
           has_evidence_context: Boolean(evidenceContext)
         }
       });
@@ -345,6 +450,11 @@ async function runRiddleProof(input) {
   let assessment;
   for (let attempt = 0; attempt < maxIterations; attempt += 1) {
     state.iterations += 1;
+    appendStageHeartbeat(state, {
+      stage: "implement",
+      summary: "Implementation stage is active.",
+      details: { iteration: state.iterations }
+    });
     appendRunEvent(state, {
       kind: "implementation.started",
       checkpoint: "implementation_started",
@@ -391,6 +501,13 @@ async function runRiddleProof(input) {
         tests_run: implementation.tests_run
       }
     });
+    appendStageHeartbeat(state, {
+      stage: "prove",
+      summary: "Proof capture stage is active.",
+      details: {
+        verification_mode: state.request.verification_mode
+      }
+    });
     appendRunEvent(state, {
       kind: "proof.started",
       checkpoint: "proof_started",
@@ -440,6 +557,13 @@ async function runRiddleProof(input) {
       stage: "verify",
       summary: "Judge adapter started."
     });
+    appendStageHeartbeat(state, {
+      stage: "verify",
+      summary: "Verification stage is active.",
+      details: {
+        verification_mode: evidenceBundle.verification_mode
+      }
+    });
     try {
       assessment = await adapters.judge.assessProof({ state, evidence_bundle: evidenceBundle });
       state.proof_decision = assessment.decision;
@@ -529,6 +653,10 @@ async function runRiddleProof(input) {
     stage: "ship",
     summary: "Ship adapter started."
   });
+  appendStageHeartbeat(state, {
+    stage: "ship",
+    summary: "Ship stage is active."
+  });
   let metadata;
   try {
     metadata = await adapters.ship.ship({ state, assessment });

package/dist/runner.d.cts

@@ -1,6 +1,7 @@
-import { SetupAdapter, ImplementationAdapter, ProofAdapter, JudgeAdapter, ShipAdapter, NotificationAdapter, RiddleProofRunParams, RiddleProofRunState, RiddleProofRunResult } from './types.cjs';
+import { PreflightAdapter, SetupAdapter, ImplementationAdapter, ProofAdapter, JudgeAdapter, ShipAdapter, NotificationAdapter, RiddleProofRunParams, RiddleProofRunState, RiddleProofRunResult } from './types.cjs';
 
 interface RiddleProofRunnerAdapters {
+    preflight?: PreflightAdapter;
     setup?: SetupAdapter;
     implementation?: ImplementationAdapter;
     proof?: ProofAdapter;

package/dist/runner.d.ts

@@ -1,6 +1,7 @@
-import { SetupAdapter, ImplementationAdapter, ProofAdapter, JudgeAdapter, ShipAdapter, NotificationAdapter, RiddleProofRunParams, RiddleProofRunState, RiddleProofRunResult } from './types.js';
+import { PreflightAdapter, SetupAdapter, ImplementationAdapter, ProofAdapter, JudgeAdapter, ShipAdapter, NotificationAdapter, RiddleProofRunParams, RiddleProofRunState, RiddleProofRunResult } from './types.js';
 
 interface RiddleProofRunnerAdapters {
+    preflight?: PreflightAdapter;
     setup?: SetupAdapter;
     implementation?: ImplementationAdapter;
     proof?: ProofAdapter;

package/dist/runner.js

@@ -1,8 +1,8 @@
 import {
   runRiddleProof
-} from "./chunk-GWGXPNON.js";
-import "./chunk-EPVZKWUS.js";
-import "./chunk-2ZQNXVQC.js";
+} from "./chunk-P3FUU5X4.js";
+import "./chunk-IQIEOQZF.js";
+import "./chunk-5DC6YXN4.js";
 export {
   runRiddleProof
 };

package/dist/state.cjs

@@ -22,7 +22,9 @@ var state_exports = {};
 __export(state_exports, {
   RIDDLE_PROOF_RUN_STATE_VERSION: () => RIDDLE_PROOF_RUN_STATE_VERSION,
   appendRunEvent: () => appendRunEvent,
+  appendStageHeartbeat: () => appendStageHeartbeat,
   createRunState: () => createRunState,
+  createRunStatusSnapshot: () => createRunStatusSnapshot,
   normalizeIntegrationContext: () => normalizeIntegrationContext,
   normalizeRunParams: () => normalizeRunParams,
   setRunStatus: () => setRunStatus
@@ -45,6 +47,17 @@ var RIDDLE_PROOF_RUN_STATE_VERSION = "riddle-proof.run-state.v1";
 function timestamp() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
+function createRunId(createdAt) {
+  const stamp = createdAt.replace(/\D/g, "").slice(0, 14) || "unknown";
+  const entropy = Math.random().toString(36).slice(2, 8) || "run";
+  return `rp_${stamp}_${entropy}`;
+}
+function elapsedMs(start, end) {
+  const startMs = start ? Date.parse(start) : NaN;
+  const endMs = end ? Date.parse(end) : NaN;
+  if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) return void 0;
+  return Math.max(0, endMs - startMs);
+}
 function normalizeIntegrationContext(input, fallbackSource) {
   const value = recordValue(input);
   if (!value) {
@@ -95,7 +108,12 @@ function createRunState(input) {
   const createdAt = input.created_at || timestamp();
   return compactRecord({
     version: RIDDLE_PROOF_RUN_STATE_VERSION,
+    run_id: input.run_id || createRunId(createdAt),
     state_path: input.state_path,
+    worktree_path: input.worktree_path,
+    branch: input.branch || input.request.branch,
+    current_stage: input.current_stage ?? null,
+    stage_started_at: input.stage_started_at ?? null,
     status: input.status || "running",
     created_at: createdAt,
     updated_at: input.updated_at || createdAt,
@@ -123,9 +141,49 @@ function appendRunEvent(state, input) {
     details: event.details
   }));
   if (input.checkpoint !== void 0) state.last_checkpoint = input.checkpoint;
+  if (input.stage !== void 0) {
+    if (state.current_stage !== input.stage) state.stage_started_at = event.ts;
+    state.current_stage = input.stage;
+  }
   state.updated_at = event.ts;
   return state;
 }
+function appendStageHeartbeat(state, input) {
+  const at = input.ts || timestamp();
+  return appendRunEvent(state, {
+    ts: at,
+    kind: "stage.heartbeat",
+    checkpoint: input.checkpoint || `${input.stage}_heartbeat`,
+    stage: input.stage,
+    summary: input.summary || `${input.stage} stage is active.`,
+    details: compactRecord({
+      elapsed_ms: elapsedMs(state.created_at, at),
+      stage_elapsed_ms: elapsedMs(state.stage_started_at, at),
+      wait_reason: input.wait_reason,
+      blocker: input.blocker,
+      ...input.details
+    })
+  });
+}
+function createRunStatusSnapshot(state, at = timestamp()) {
+  const latestEvent = state.events[state.events.length - 1];
+  const runId = state.run_id || "unknown";
+  return compactRecord({
+    run_id: runId,
+    status: state.status,
+    current_stage: state.current_stage ?? null,
+    state_path: state.state_path ?? null,
+    worktree_path: state.worktree_path ?? null,
+    branch: state.branch ?? null,
+    iterations: state.iterations,
+    last_checkpoint: state.last_checkpoint ?? null,
+    updated_at: state.updated_at,
+    elapsed_ms: elapsedMs(state.created_at, at),
+    stage_elapsed_ms: elapsedMs(state.stage_started_at, at),
+    blocker: state.blocker,
+    latest_event: latestEvent
+  });
+}
 function setRunStatus(state, status, at = timestamp()) {
   state.status = status;
   state.ok = status !== "blocked" && status !== "failed";
@@ -136,7 +194,9 @@ function setRunStatus(state, status, at = timestamp()) {
 0 && (module.exports = {
   RIDDLE_PROOF_RUN_STATE_VERSION,
   appendRunEvent,
+  appendStageHeartbeat,
   createRunState,
+  createRunStatusSnapshot,
   normalizeIntegrationContext,
   normalizeRunParams,
   setRunStatus

package/dist/state.d.cts

@@ -1,10 +1,15 @@
-import { RiddleProofRunParams, RiddleProofStatus, RiddleProofEvent, RiddleProofRunState, IntegrationContext } from './types.cjs';
+import { RiddleProofRunParams, RiddleProofStatus, RiddleProofStage, RiddleProofEvent, RiddleProofRunState, RiddleProofRunStatusSnapshot, IntegrationContext } from './types.cjs';
 
 declare const RIDDLE_PROOF_RUN_STATE_VERSION: "riddle-proof.run-state.v1";
 interface CreateRunStateInput {
     request: RiddleProofRunParams;
+    run_id?: string;
     status?: RiddleProofStatus;
     state_path?: string;
+    worktree_path?: string;
+    branch?: string;
+    current_stage?: RiddleProofStage | null;
+    stage_started_at?: string | null;
     created_at?: string;
     updated_at?: string;
     iterations?: number;
@@ -18,6 +23,16 @@ declare function normalizeIntegrationContext(input?: Partial<IntegrationContext>
 declare function normalizeRunParams(input: RiddleProofRunParams): RiddleProofRunParams;
 declare function createRunState(input: CreateRunStateInput): RiddleProofRunState;
 declare function appendRunEvent<T extends RiddleProofRunState>(state: T, input: RunEventInput): T;
+declare function appendStageHeartbeat<T extends RiddleProofRunState>(state: T, input: {
+    stage: RiddleProofStage;
+    summary?: string;
+    checkpoint?: string;
+    wait_reason?: string;
+    blocker?: string;
+    details?: Record<string, unknown>;
+    ts?: string;
+}): T;
+declare function createRunStatusSnapshot(state: RiddleProofRunState, at?: string): RiddleProofRunStatusSnapshot;
 declare function setRunStatus<T extends RiddleProofRunState>(state: T, status: RiddleProofStatus, at?: string): T;
 
-export { type CreateRunStateInput, RIDDLE_PROOF_RUN_STATE_VERSION, type RunEventInput, appendRunEvent, createRunState, normalizeIntegrationContext, normalizeRunParams, setRunStatus };
+export { type CreateRunStateInput, RIDDLE_PROOF_RUN_STATE_VERSION, type RunEventInput, appendRunEvent, appendStageHeartbeat, createRunState, createRunStatusSnapshot, normalizeIntegrationContext, normalizeRunParams, setRunStatus };

package/dist/state.d.ts

@@ -1,10 +1,15 @@
-import { RiddleProofRunParams, RiddleProofStatus, RiddleProofEvent, RiddleProofRunState, IntegrationContext } from './types.js';
+import { RiddleProofRunParams, RiddleProofStatus, RiddleProofStage, RiddleProofEvent, RiddleProofRunState, RiddleProofRunStatusSnapshot, IntegrationContext } from './types.js';
 
 declare const RIDDLE_PROOF_RUN_STATE_VERSION: "riddle-proof.run-state.v1";
 interface CreateRunStateInput {
     request: RiddleProofRunParams;
+    run_id?: string;
     status?: RiddleProofStatus;
     state_path?: string;
+    worktree_path?: string;
+    branch?: string;
+    current_stage?: RiddleProofStage | null;
+    stage_started_at?: string | null;
     created_at?: string;
     updated_at?: string;
     iterations?: number;
@@ -18,6 +23,16 @@ declare function normalizeIntegrationContext(input?: Partial<IntegrationContext>
 declare function normalizeRunParams(input: RiddleProofRunParams): RiddleProofRunParams;
 declare function createRunState(input: CreateRunStateInput): RiddleProofRunState;
 declare function appendRunEvent<T extends RiddleProofRunState>(state: T, input: RunEventInput): T;
+declare function appendStageHeartbeat<T extends RiddleProofRunState>(state: T, input: {
+    stage: RiddleProofStage;
+    summary?: string;
+    checkpoint?: string;
+    wait_reason?: string;
+    blocker?: string;
+    details?: Record<string, unknown>;
+    ts?: string;
+}): T;
+declare function createRunStatusSnapshot(state: RiddleProofRunState, at?: string): RiddleProofRunStatusSnapshot;
 declare function setRunStatus<T extends RiddleProofRunState>(state: T, status: RiddleProofStatus, at?: string): T;
 
-export { type CreateRunStateInput, RIDDLE_PROOF_RUN_STATE_VERSION, type RunEventInput, appendRunEvent, createRunState, normalizeIntegrationContext, normalizeRunParams, setRunStatus };
+export { type CreateRunStateInput, RIDDLE_PROOF_RUN_STATE_VERSION, type RunEventInput, appendRunEvent, appendStageHeartbeat, createRunState, createRunStatusSnapshot, normalizeIntegrationContext, normalizeRunParams, setRunStatus };

package/dist/state.js

@@ -1,16 +1,20 @@
 import {
   RIDDLE_PROOF_RUN_STATE_VERSION,
   appendRunEvent,
+  appendStageHeartbeat,
   createRunState,
+  createRunStatusSnapshot,
   normalizeIntegrationContext,
   normalizeRunParams,
   setRunStatus
-} from "./chunk-EPVZKWUS.js";
-import "./chunk-2ZQNXVQC.js";
+} from "./chunk-IQIEOQZF.js";
+import "./chunk-5DC6YXN4.js";
 export {
   RIDDLE_PROOF_RUN_STATE_VERSION,
   appendRunEvent,
+  appendStageHeartbeat,
   createRunState,
+  createRunStatusSnapshot,
   normalizeIntegrationContext,
   normalizeRunParams,
   setRunStatus

package/dist/types.d.cts

@@ -6,7 +6,8 @@ type JsonObject = {
 type RiddleProofStatus = "running" | "blocked" | "failed" | "ready_to_ship" | "shipped" | "completed";
 type RiddleProofVerificationMode = "proof" | "visual" | "interaction" | "render" | "data" | "json" | "audio" | "log" | "logs" | "metric" | "metrics" | (string & {});
 type RiddleProofDecision = "ready_to_ship" | "needs_richer_proof" | "revise_capture" | "needs_recon" | "needs_implementation" | (string & {});
-type RiddleProofStage = "setup" | "recon" | "author" | "implement" | "prove" | "verify" | "ship" | "notify" | (string & {});
+type RiddleProofStage = "preflight" | "setup" | "recon" | "author" | "implement" | "prove" | "verify" | "ship" | "notify" | (string & {});
+type RiddleProofArtifactRole = "baseline" | "after_proof" | "incidental" | "diagnostic" | (string & {});
 interface RiddleProofRunParams {
     repo?: string;
     branch?: string;
@@ -60,7 +61,12 @@ interface RiddleProofEvent {
 }
 interface RiddleProofRunState {
     version: "riddle-proof.run-state.v1";
+    run_id?: string;
     state_path?: string;
+    worktree_path?: string;
+    branch?: string;
+    current_stage?: RiddleProofStage | null;
+    stage_started_at?: string | null;
     status: RiddleProofStatus;
     ok?: boolean;
     created_at: string;
@@ -80,7 +86,11 @@ interface RiddleProofRunState {
 interface RiddleProofRunResult {
     ok: boolean;
     status: RiddleProofStatus;
+    run_id?: string;
     state_path?: string | null;
+    worktree_path?: string | null;
+    branch?: string | null;
+    current_stage?: RiddleProofStage | null;
     iterations?: number;
     last_checkpoint?: string | null;
     last_summary?: string | null;
@@ -95,6 +105,21 @@ interface RiddleProofRunResult {
     evidence_bundle?: RiddleProofEvidenceBundle;
     raw?: Record<string, unknown>;
 }
+interface RiddleProofRunStatusSnapshot {
+    run_id: string;
+    status: RiddleProofStatus;
+    current_stage?: RiddleProofStage | null;
+    state_path?: string | null;
+    worktree_path?: string | null;
+    branch?: string | null;
+    iterations: number;
+    last_checkpoint?: string | null;
+    updated_at: string;
+    elapsed_ms?: number;
+    stage_elapsed_ms?: number;
+    blocker?: RiddleProofBlocker;
+    latest_event?: RiddleProofEvent;
+}
 interface RiddleProofEvidenceBundle {
     verification_mode: RiddleProofVerificationMode;
     baselines?: EvidenceReference[];
@@ -108,6 +133,7 @@ interface RiddleProofEvidenceBundle {
 }
 interface EvidenceReference {
     kind: "before" | "prod" | "after" | "comparison" | (string & {});
+    role?: RiddleProofArtifactRole;
     url?: string;
     path?: string;
     observed_path?: string;
@@ -117,6 +143,7 @@ interface EvidenceReference {
 interface EvidenceArtifact {
     name: string;
     kind?: "screenshot" | "json" | "log" | "metric" | "audio" | "video" | (string & {});
+    role?: RiddleProofArtifactRole;
     url?: string;
     path?: string;
     content_type?: string;
@@ -132,6 +159,20 @@ interface RiddleProofAssessment {
     reasons?: string[];
     source?: "supervising_agent" | "supervisor" | "human" | (string & {});
 }
+interface PreflightAdapterInput {
+    request: RiddleProofRunParams;
+    state: RiddleProofRunState;
+}
+interface PreflightAdapterResult {
+    ok: boolean;
+    warnings?: string[];
+    degraded_capabilities?: string[];
+    blockers?: string[];
+    raw?: Record<string, unknown>;
+}
+interface PreflightAdapter {
+    preflight(input: PreflightAdapterInput): Promise<PreflightAdapterResult>;
+}
 interface SetupAdapterInput {
     request: RiddleProofRunParams;
     state: RiddleProofRunState;
@@ -139,6 +180,9 @@ interface SetupAdapterInput {
 interface SetupAdapterResult {
     ok: boolean;
     workdir?: string;
+    worktree_path?: string;
+    branch?: string;
+    cleanup_policy?: "reuse" | "delete_on_success" | "delete_on_finish" | "leave_for_debug" | (string & {});
     evidence_context?: RiddleProofEvidenceBundle;
     blockers?: string[];
     raw?: Record<string, unknown>;
@@ -204,4 +248,4 @@ interface RiddleProofTerminalMetadata {
     finalized?: boolean;
 }
 
-export type { EvidenceArtifact, EvidenceReference, ImplementationAdapter, ImplementationAdapterInput, ImplementationAdapterResult, IntegrationContext, JsonObject, JsonPrimitive, JsonValue, JudgeAdapter, NotificationAdapter, ProofAdapter, ProofAdapterInput, ProofAdapterResult, RiddleProofAssessment, RiddleProofBlocker, RiddleProofDecision, RiddleProofEvent, RiddleProofEvidenceBundle, RiddleProofRunParams, RiddleProofRunResult, RiddleProofRunState, RiddleProofStage, RiddleProofStatus, RiddleProofTerminalMetadata, RiddleProofVerificationMode, SetupAdapter, SetupAdapterInput, SetupAdapterResult, ShipAdapter };
+export type { EvidenceArtifact, EvidenceReference, ImplementationAdapter, ImplementationAdapterInput, ImplementationAdapterResult, IntegrationContext, JsonObject, JsonPrimitive, JsonValue, JudgeAdapter, NotificationAdapter, PreflightAdapter, PreflightAdapterInput, PreflightAdapterResult, ProofAdapter, ProofAdapterInput, ProofAdapterResult, RiddleProofArtifactRole, RiddleProofAssessment, RiddleProofBlocker, RiddleProofDecision, RiddleProofEvent, RiddleProofEvidenceBundle, RiddleProofRunParams, RiddleProofRunResult, RiddleProofRunState, RiddleProofRunStatusSnapshot, RiddleProofStage, RiddleProofStatus, RiddleProofTerminalMetadata, RiddleProofVerificationMode, SetupAdapter, SetupAdapterInput, SetupAdapterResult, ShipAdapter };

package/dist/types.d.ts

@@ -6,7 +6,8 @@ type JsonObject = {
 type RiddleProofStatus = "running" | "blocked" | "failed" | "ready_to_ship" | "shipped" | "completed";
 type RiddleProofVerificationMode = "proof" | "visual" | "interaction" | "render" | "data" | "json" | "audio" | "log" | "logs" | "metric" | "metrics" | (string & {});
 type RiddleProofDecision = "ready_to_ship" | "needs_richer_proof" | "revise_capture" | "needs_recon" | "needs_implementation" | (string & {});
-type RiddleProofStage = "setup" | "recon" | "author" | "implement" | "prove" | "verify" | "ship" | "notify" | (string & {});
+type RiddleProofStage = "preflight" | "setup" | "recon" | "author" | "implement" | "prove" | "verify" | "ship" | "notify" | (string & {});
+type RiddleProofArtifactRole = "baseline" | "after_proof" | "incidental" | "diagnostic" | (string & {});
 interface RiddleProofRunParams {
     repo?: string;
     branch?: string;
@@ -60,7 +61,12 @@ interface RiddleProofEvent {
 }
 interface RiddleProofRunState {
     version: "riddle-proof.run-state.v1";
+    run_id?: string;
     state_path?: string;
+    worktree_path?: string;
+    branch?: string;
+    current_stage?: RiddleProofStage | null;
+    stage_started_at?: string | null;
     status: RiddleProofStatus;
     ok?: boolean;
     created_at: string;
@@ -80,7 +86,11 @@ interface RiddleProofRunState {
 interface RiddleProofRunResult {
     ok: boolean;
     status: RiddleProofStatus;
+    run_id?: string;
     state_path?: string | null;
+    worktree_path?: string | null;
+    branch?: string | null;
+    current_stage?: RiddleProofStage | null;
     iterations?: number;
     last_checkpoint?: string | null;
     last_summary?: string | null;
@@ -95,6 +105,21 @@ interface RiddleProofRunResult {
     evidence_bundle?: RiddleProofEvidenceBundle;
     raw?: Record<string, unknown>;
 }
+interface RiddleProofRunStatusSnapshot {
+    run_id: string;
+    status: RiddleProofStatus;
+    current_stage?: RiddleProofStage | null;
+    state_path?: string | null;
+    worktree_path?: string | null;
+    branch?: string | null;
+    iterations: number;
+    last_checkpoint?: string | null;
+    updated_at: string;
+    elapsed_ms?: number;
+    stage_elapsed_ms?: number;
+    blocker?: RiddleProofBlocker;
+    latest_event?: RiddleProofEvent;
+}
 interface RiddleProofEvidenceBundle {
     verification_mode: RiddleProofVerificationMode;
     baselines?: EvidenceReference[];
@@ -108,6 +133,7 @@ interface RiddleProofEvidenceBundle {
 }
 interface EvidenceReference {
     kind: "before" | "prod" | "after" | "comparison" | (string & {});
+    role?: RiddleProofArtifactRole;
     url?: string;
     path?: string;
     observed_path?: string;
@@ -117,6 +143,7 @@ interface EvidenceReference {
 interface EvidenceArtifact {
     name: string;
     kind?: "screenshot" | "json" | "log" | "metric" | "audio" | "video" | (string & {});
+    role?: RiddleProofArtifactRole;
     url?: string;
     path?: string;
     content_type?: string;
@@ -132,6 +159,20 @@ interface RiddleProofAssessment {
     reasons?: string[];
     source?: "supervising_agent" | "supervisor" | "human" | (string & {});
 }
+interface PreflightAdapterInput {
+    request: RiddleProofRunParams;
+    state: RiddleProofRunState;
+}
+interface PreflightAdapterResult {
+    ok: boolean;
+    warnings?: string[];
+    degraded_capabilities?: string[];
+    blockers?: string[];
+    raw?: Record<string, unknown>;
+}
+interface PreflightAdapter {
+    preflight(input: PreflightAdapterInput): Promise<PreflightAdapterResult>;
+}
 interface SetupAdapterInput {
     request: RiddleProofRunParams;
     state: RiddleProofRunState;
@@ -139,6 +180,9 @@ interface SetupAdapterInput {
 interface SetupAdapterResult {
     ok: boolean;
     workdir?: string;
+    worktree_path?: string;
+    branch?: string;
+    cleanup_policy?: "reuse" | "delete_on_success" | "delete_on_finish" | "leave_for_debug" | (string & {});
     evidence_context?: RiddleProofEvidenceBundle;
     blockers?: string[];
     raw?: Record<string, unknown>;
@@ -204,4 +248,4 @@ interface RiddleProofTerminalMetadata {
     finalized?: boolean;
 }
 
-export type { EvidenceArtifact, EvidenceReference, ImplementationAdapter, ImplementationAdapterInput, ImplementationAdapterResult, IntegrationContext, JsonObject, JsonPrimitive, JsonValue, JudgeAdapter, NotificationAdapter, ProofAdapter, ProofAdapterInput, ProofAdapterResult, RiddleProofAssessment, RiddleProofBlocker, RiddleProofDecision, RiddleProofEvent, RiddleProofEvidenceBundle, RiddleProofRunParams, RiddleProofRunResult, RiddleProofRunState, RiddleProofStage, RiddleProofStatus, RiddleProofTerminalMetadata, RiddleProofVerificationMode, SetupAdapter, SetupAdapterInput, SetupAdapterResult, ShipAdapter };
+export type { EvidenceArtifact, EvidenceReference, ImplementationAdapter, ImplementationAdapterInput, ImplementationAdapterResult, IntegrationContext, JsonObject, JsonPrimitive, JsonValue, JudgeAdapter, NotificationAdapter, PreflightAdapter, PreflightAdapterInput, PreflightAdapterResult, ProofAdapter, ProofAdapterInput, ProofAdapterResult, RiddleProofArtifactRole, RiddleProofAssessment, RiddleProofBlocker, RiddleProofDecision, RiddleProofEvent, RiddleProofEvidenceBundle, RiddleProofRunParams, RiddleProofRunResult, RiddleProofRunState, RiddleProofRunStatusSnapshot, RiddleProofStage, RiddleProofStatus, RiddleProofTerminalMetadata, RiddleProofVerificationMode, SetupAdapter, SetupAdapterInput, SetupAdapterResult, ShipAdapter };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riddledc/riddle-proof",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Reusable Riddle Proof contracts and helpers for evidence-backed agent changes.",
   "license": "MIT",
   "author": "RiddleDC",