@riddledc/riddle-proof 0.2.0 → 0.4.0

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;
@@ -34,6 +35,11 @@ interface RiddleProofRunParams {
     color_scheme?: "dark" | "light" | (string & {});
     wait_for_selector?: string;
     ship_mode?: "none" | "ship";
+    engine_state_path?: string;
+    harness_state_path?: string;
+    max_iterations?: number;
+    auto_approve?: boolean;
+    dry_run?: boolean;
     integration_context?: IntegrationContext;
 }
 interface IntegrationContext {
@@ -60,7 +66,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 +91,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 +110,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 +138,7 @@ interface RiddleProofEvidenceBundle {
 }
 interface EvidenceReference {
     kind: "before" | "prod" | "after" | "comparison" | (string & {});
+    role?: RiddleProofArtifactRole;
     url?: string;
     path?: string;
     observed_path?: string;
@@ -117,6 +148,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 +164,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 +185,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 +253,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;
@@ -34,6 +35,11 @@ interface RiddleProofRunParams {
     color_scheme?: "dark" | "light" | (string & {});
     wait_for_selector?: string;
     ship_mode?: "none" | "ship";
+    engine_state_path?: string;
+    harness_state_path?: string;
+    max_iterations?: number;
+    auto_approve?: boolean;
+    dry_run?: boolean;
     integration_context?: IntegrationContext;
 }
 interface IntegrationContext {
@@ -60,7 +66,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 +91,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 +110,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 +138,7 @@ interface RiddleProofEvidenceBundle {
 }
 interface EvidenceReference {
     kind: "before" | "prod" | "after" | "comparison" | (string & {});
+    role?: RiddleProofArtifactRole;
     url?: string;
     path?: string;
     observed_path?: string;
@@ -117,6 +148,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 +164,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 +185,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 +253,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.4.0",
   "description": "Reusable Riddle Proof contracts and helpers for evidence-backed agent changes.",
   "license": "MIT",
   "author": "RiddleDC",
@@ -39,6 +39,11 @@
       "import": "./dist/runner.js",
       "require": "./dist/runner.cjs"
     },
+    "./engine-harness": {
+      "types": "./dist/engine-harness.d.ts",
+      "import": "./dist/engine-harness.js",
+      "require": "./dist/engine-harness.cjs"
+    },
     "./openclaw": {
       "types": "./dist/openclaw.d.ts",
       "import": "./dist/openclaw.js",
@@ -60,7 +65,7 @@
     "typescript": "^5.4.5"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/types.ts src/result.ts src/state.ts src/runner.ts src/openclaw.ts --format cjs,esm --dts --out-dir dist --clean",
+    "build": "tsup src/index.ts src/types.ts src/result.ts src/state.ts src/runner.ts src/engine-harness.ts src/openclaw.ts --format cjs,esm --dts --out-dir dist --clean",
     "clean": "rm -rf dist",
     "lint": "echo 'lint: (not configured)'",
     "test": "npm run build && node test.js"