@riddledc/riddle-proof 0.5.33 → 0.5.34

package/dist/proof-session.d.ts

@@ -0,0 +1,37 @@
+import { RiddleProofVisualSession, JsonValue, RiddleProofVisualSessionFingerprintBasis } from './types.js';
+
+declare const RIDDLE_PROOF_VISUAL_SESSION_VERSION: "riddle-proof.visual-session.v1";
+declare const RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_VERSION: "riddle-proof.visual-session.fingerprint.v1";
+interface BuildVisualProofSessionInput {
+    run_id?: string;
+    parent?: RiddleProofVisualSession | null;
+    repo?: string;
+    branch?: string;
+    route?: string;
+    observed_after_path?: string;
+    reference?: string;
+    verification_mode?: string;
+    target_image_url?: string;
+    target_image_hash?: string;
+    viewport_matrix?: JsonValue;
+    deterministic_setup?: JsonValue;
+    proof_plan?: string;
+    capture_script?: string;
+    wait_for_selector?: string;
+    assertions?: JsonValue;
+    artifacts?: RiddleProofVisualSession["artifacts"];
+    evidence?: RiddleProofVisualSession["evidence"];
+    status?: string;
+}
+interface VisualProofSessionMismatch {
+    key: string;
+    expected: JsonValue | undefined;
+    actual: JsonValue | undefined;
+}
+declare function visualSessionFingerprintBasis(input: BuildVisualProofSessionInput): RiddleProofVisualSessionFingerprintBasis;
+declare function visualSessionFingerprint(input: BuildVisualProofSessionInput | RiddleProofVisualSessionFingerprintBasis): string;
+declare function buildVisualProofSession(input: BuildVisualProofSessionInput): RiddleProofVisualSession;
+declare function parseVisualProofSession(value: unknown): RiddleProofVisualSession;
+declare function compareVisualProofSessionFingerprint(parent: RiddleProofVisualSession, input: BuildVisualProofSessionInput): VisualProofSessionMismatch[];
+
+export { type BuildVisualProofSessionInput, RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_VERSION, RIDDLE_PROOF_VISUAL_SESSION_VERSION, type VisualProofSessionMismatch, buildVisualProofSession, compareVisualProofSessionFingerprint, parseVisualProofSession, visualSessionFingerprint, visualSessionFingerprintBasis };

package/dist/proof-session.js

@@ -0,0 +1,18 @@
+import {
+  RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_VERSION,
+  RIDDLE_PROOF_VISUAL_SESSION_VERSION,
+  buildVisualProofSession,
+  compareVisualProofSessionFingerprint,
+  parseVisualProofSession,
+  visualSessionFingerprint,
+  visualSessionFingerprintBasis
+} from "./chunk-ODORKNSO.js";
+export {
+  RIDDLE_PROOF_VISUAL_SESSION_FINGERPRINT_VERSION,
+  RIDDLE_PROOF_VISUAL_SESSION_VERSION,
+  buildVisualProofSession,
+  compareVisualProofSessionFingerprint,
+  parseVisualProofSession,
+  visualSessionFingerprint,
+  visualSessionFingerprintBasis
+};

package/dist/result.cjs

@@ -233,6 +233,7 @@ function createRunResult(input) {
     merge_recommendation: state.merge_recommendation,
     finalized: state.finalized,
     blocker: state.blocker,
+    proof_session: state.proof_session,
     evidence_bundle: input.evidence_bundle,
     raw: input.raw
   });

package/dist/result.js

@@ -7,7 +7,7 @@ import {
   nonEmptyString,
   normalizeTerminalMetadata,
   recordValue
-} from "./chunk-TMMKRKY5.js";
+} from "./chunk-J2MERROF.js";
 export {
   applyTerminalMetadata,
   compactRecord,

package/dist/runner.cjs

@@ -123,6 +123,7 @@ function createRunResult(input) {
     merge_recommendation: state.merge_recommendation,
     finalized: state.finalized,
     blocker: state.blocker,
+    proof_session: state.proof_session,
     evidence_bundle: input.evidence_bundle,
     raw: input.raw
   });
@@ -170,6 +171,11 @@ function normalizeRunParams(input) {
     success_criteria: input.success_criteria,
     assertions: input.assertions,
     verification_mode: input.verification_mode,
+    resume_session: input.resume_session,
+    target_image_url: input.target_image_url,
+    target_image_hash: input.target_image_hash,
+    viewport_matrix: input.viewport_matrix,
+    deterministic_setup: input.deterministic_setup,
     reference: input.reference,
     base_branch: input.base_branch,
     before_ref: input.before_ref,

package/dist/runner.js

@@ -1,8 +1,8 @@
 import {
   runRiddleProof
-} from "./chunk-F6VFKS7K.js";
-import "./chunk-7ZJAUEUN.js";
-import "./chunk-TMMKRKY5.js";
+} from "./chunk-MQ2BHHLX.js";
+import "./chunk-OASB3CYU.js";
+import "./chunk-J2MERROF.js";
 export {
   runRiddleProof
 };

package/dist/state.cjs

@@ -119,6 +119,11 @@ function normalizeRunParams(input) {
     success_criteria: input.success_criteria,
     assertions: input.assertions,
     verification_mode: input.verification_mode,
+    resume_session: input.resume_session,
+    target_image_url: input.target_image_url,
+    target_image_hash: input.target_image_hash,
+    viewport_matrix: input.viewport_matrix,
+    deterministic_setup: input.deterministic_setup,
     reference: input.reference,
     base_branch: input.base_branch,
     before_ref: input.before_ref,

package/dist/state.js

@@ -9,8 +9,8 @@ import {
   normalizePrLifecycleState,
   normalizeRunParams,
   setRunStatus
-} from "./chunk-7ZJAUEUN.js";
-import "./chunk-TMMKRKY5.js";
+} from "./chunk-OASB3CYU.js";
+import "./chunk-J2MERROF.js";
 export {
   RIDDLE_PROOF_RUN_STATE_VERSION,
   appendRunEvent,

package/dist/types.d.cts

@@ -19,6 +19,11 @@ interface RiddleProofRunParams {
     success_criteria?: string;
     assertions?: JsonValue;
     verification_mode?: RiddleProofVerificationMode;
+    resume_session?: string;
+    target_image_url?: string;
+    target_image_hash?: string;
+    viewport_matrix?: JsonValue;
+    deterministic_setup?: JsonValue;
     reference?: "prod" | "before" | "both";
     base_branch?: string;
     before_ref?: string;
@@ -105,6 +110,7 @@ interface RiddleProofRunState {
     merge_recommendation?: string;
     implementation_detection_summary?: string | null;
     implementation_detection?: Record<string, unknown> | null;
+    proof_session?: RiddleProofVisualSession;
     finalized?: boolean;
     blocker?: RiddleProofBlocker;
     events: RiddleProofEvent[];
@@ -142,6 +148,7 @@ interface RiddleProofRunResult {
     merge_recommendation?: string;
     finalized?: boolean;
     blocker?: RiddleProofBlocker;
+    proof_session?: RiddleProofVisualSession;
     evidence_bundle?: RiddleProofEvidenceBundle;
     raw?: Record<string, unknown>;
 }
@@ -179,6 +186,7 @@ interface RiddleProofEvidenceBundle {
     baselines?: EvidenceReference[];
     after?: EvidenceReference;
     artifacts?: EvidenceArtifact[];
+    proof_session?: RiddleProofVisualSession;
     proof_evidence?: unknown;
     proof_evidence_sample?: unknown;
     assertions?: JsonValue;
@@ -331,5 +339,63 @@ interface RiddleProofPrLifecycleState {
     next_action?: string;
     cleanup?: Record<string, unknown>;
 }
+interface RiddleProofVisualSession {
+    version: "riddle-proof.visual-session.v1";
+    session_id: string;
+    run_id?: string;
+    parent_session_id?: string | null;
+    parent_fingerprint?: string | null;
+    created_at: string;
+    fingerprint: string;
+    fingerprint_basis: RiddleProofVisualSessionFingerprintBasis;
+    repo?: string;
+    branch?: string;
+    route?: {
+        path?: string;
+        observed_after_path?: string;
+    };
+    reference?: string;
+    verification_mode?: string;
+    target_image?: {
+        url?: string;
+        hash?: string;
+    };
+    viewport_matrix?: JsonValue;
+    deterministic_setup?: JsonValue;
+    capture?: {
+        proof_plan?: string;
+        capture_script?: string;
+        wait_for_selector?: string;
+    };
+    assertions?: JsonValue;
+    artifacts?: {
+        before?: string;
+        prod?: string;
+        after?: string;
+        session?: string;
+        outputs?: EvidenceArtifact[];
+    };
+    evidence?: {
+        visual_delta?: JsonValue;
+        semantic_context?: JsonValue;
+        artifact_contract?: JsonValue;
+        artifact_usage?: JsonValue;
+    };
+    status?: string;
+}
+interface RiddleProofVisualSessionFingerprintBasis {
+    version: "riddle-proof.visual-session.fingerprint.v1";
+    repo?: string;
+    route?: string;
+    wait_for_selector?: string;
+    reference?: string;
+    verification_mode?: string;
+    target_image_url?: string;
+    target_image_hash?: string;
+    viewport_matrix?: JsonValue;
+    deterministic_setup?: JsonValue;
+    assertions?: JsonValue;
+    capture_script_hash?: string;
+}
 
-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, RiddleProofPrLifecycleState, RiddleProofPrLifecycleStatus, RiddleProofRunParams, RiddleProofRunResult, RiddleProofRunState, RiddleProofRunStatusSnapshot, 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, RiddleProofPrLifecycleState, RiddleProofPrLifecycleStatus, RiddleProofRunParams, RiddleProofRunResult, RiddleProofRunState, RiddleProofRunStatusSnapshot, RiddleProofStage, RiddleProofStatus, RiddleProofTerminalMetadata, RiddleProofVerificationMode, RiddleProofVisualSession, RiddleProofVisualSessionFingerprintBasis, SetupAdapter, SetupAdapterInput, SetupAdapterResult, ShipAdapter };

package/dist/types.d.ts

@@ -19,6 +19,11 @@ interface RiddleProofRunParams {
     success_criteria?: string;
     assertions?: JsonValue;
     verification_mode?: RiddleProofVerificationMode;
+    resume_session?: string;
+    target_image_url?: string;
+    target_image_hash?: string;
+    viewport_matrix?: JsonValue;
+    deterministic_setup?: JsonValue;
     reference?: "prod" | "before" | "both";
     base_branch?: string;
     before_ref?: string;
@@ -105,6 +110,7 @@ interface RiddleProofRunState {
     merge_recommendation?: string;
     implementation_detection_summary?: string | null;
     implementation_detection?: Record<string, unknown> | null;
+    proof_session?: RiddleProofVisualSession;
     finalized?: boolean;
     blocker?: RiddleProofBlocker;
     events: RiddleProofEvent[];
@@ -142,6 +148,7 @@ interface RiddleProofRunResult {
     merge_recommendation?: string;
     finalized?: boolean;
     blocker?: RiddleProofBlocker;
+    proof_session?: RiddleProofVisualSession;
     evidence_bundle?: RiddleProofEvidenceBundle;
     raw?: Record<string, unknown>;
 }
@@ -179,6 +186,7 @@ interface RiddleProofEvidenceBundle {
     baselines?: EvidenceReference[];
     after?: EvidenceReference;
     artifacts?: EvidenceArtifact[];
+    proof_session?: RiddleProofVisualSession;
     proof_evidence?: unknown;
     proof_evidence_sample?: unknown;
     assertions?: JsonValue;
@@ -331,5 +339,63 @@ interface RiddleProofPrLifecycleState {
     next_action?: string;
     cleanup?: Record<string, unknown>;
 }
+interface RiddleProofVisualSession {
+    version: "riddle-proof.visual-session.v1";
+    session_id: string;
+    run_id?: string;
+    parent_session_id?: string | null;
+    parent_fingerprint?: string | null;
+    created_at: string;
+    fingerprint: string;
+    fingerprint_basis: RiddleProofVisualSessionFingerprintBasis;
+    repo?: string;
+    branch?: string;
+    route?: {
+        path?: string;
+        observed_after_path?: string;
+    };
+    reference?: string;
+    verification_mode?: string;
+    target_image?: {
+        url?: string;
+        hash?: string;
+    };
+    viewport_matrix?: JsonValue;
+    deterministic_setup?: JsonValue;
+    capture?: {
+        proof_plan?: string;
+        capture_script?: string;
+        wait_for_selector?: string;
+    };
+    assertions?: JsonValue;
+    artifacts?: {
+        before?: string;
+        prod?: string;
+        after?: string;
+        session?: string;
+        outputs?: EvidenceArtifact[];
+    };
+    evidence?: {
+        visual_delta?: JsonValue;
+        semantic_context?: JsonValue;
+        artifact_contract?: JsonValue;
+        artifact_usage?: JsonValue;
+    };
+    status?: string;
+}
+interface RiddleProofVisualSessionFingerprintBasis {
+    version: "riddle-proof.visual-session.fingerprint.v1";
+    repo?: string;
+    route?: string;
+    wait_for_selector?: string;
+    reference?: string;
+    verification_mode?: string;
+    target_image_url?: string;
+    target_image_hash?: string;
+    viewport_matrix?: JsonValue;
+    deterministic_setup?: JsonValue;
+    assertions?: JsonValue;
+    capture_script_hash?: string;
+}
 
-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, RiddleProofPrLifecycleState, RiddleProofPrLifecycleStatus, RiddleProofRunParams, RiddleProofRunResult, RiddleProofRunState, RiddleProofRunStatusSnapshot, 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, RiddleProofPrLifecycleState, RiddleProofPrLifecycleStatus, RiddleProofRunParams, RiddleProofRunResult, RiddleProofRunState, RiddleProofRunStatusSnapshot, RiddleProofStage, RiddleProofStatus, RiddleProofTerminalMetadata, RiddleProofVerificationMode, RiddleProofVisualSession, RiddleProofVisualSessionFingerprintBasis, SetupAdapter, SetupAdapterInput, SetupAdapterResult, ShipAdapter };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riddledc/riddle-proof",
-  "version": "0.5.33",
+  "version": "0.5.34",
   "description": "Reusable Riddle Proof contracts and helpers for evidence-backed agent changes.",
   "license": "MIT",
   "author": "RiddleDC",
@@ -49,6 +49,11 @@
       "import": "./dist/diagnostics.js",
       "require": "./dist/diagnostics.cjs"
     },
+    "./proof-session": {
+      "types": "./dist/proof-session.d.ts",
+      "import": "./dist/proof-session.js",
+      "require": "./dist/proof-session.cjs"
+    },
     "./openclaw": {
       "types": "./dist/openclaw.d.ts",
       "import": "./dist/openclaw.js",
@@ -82,7 +87,7 @@
     "typescript": "^5.4.5"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/types.ts src/result.ts src/state.ts src/runner.ts src/engine-harness.ts src/diagnostics.ts src/openclaw.ts src/proof-run-core.ts src/proof-run-engine.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/diagnostics.ts src/proof-session.ts src/openclaw.ts src/proof-run-core.ts src/proof-run-engine.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 && node proof-run.test.js"

package/runtime/lib/preflight.py

@@ -8,7 +8,16 @@ capture_script: optional at setup and recon; required before verify.
 
 import json, os, re, time, uuid, sys
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from util import STATE_FILE, ARGS_FILE, save_state, invoke, load_package_json
+from util import (
+    STATE_FILE,
+    ARGS_FILE,
+    apply_proof_session_defaults,
+    invoke,
+    load_package_json,
+    load_proof_session_source,
+    save_state,
+    validate_proof_session_resume,
+)
 
 def truthy(value):
     return str(value or '').strip().lower() in ('1', 'true', 'yes', 'y', 'on')
@@ -40,6 +49,19 @@ if not os.path.exists(args_file):
 with open(args_file) as f:
     s = json.load(f)
 
+resume_session_source = (s.get('resume_session') or '').strip()
+if resume_session_source:
+    parent_proof_session = load_proof_session_source(resume_session_source)
+    s['parent_proof_session'] = parent_proof_session
+    s['parent_proof_session_id'] = parent_proof_session.get('session_id')
+    s['proof_session_resume'] = {
+        'status': 'loaded',
+        'source': 'inline_json' if resume_session_source.startswith('{') else resume_session_source,
+        'parent_session_id': parent_proof_session.get('session_id'),
+        'parent_fingerprint': parent_proof_session.get('fingerprint'),
+        'applied_fields': apply_proof_session_defaults(s, parent_proof_session),
+    }
+
 mode = (s.get('mode') or '').strip().lower()
 reference = s.get('reference', 'both')
 requested_reference = reference
@@ -107,6 +129,8 @@ if raw_assertions:
     except Exception as e:
         raise SystemExit('assertions_json is not valid JSON: ' + str(e))
 s['parsed_assertions'] = parsed_assertions
+s['viewport_matrix'] = parse_json_arg('viewport_matrix_json', (dict, list), None)
+s['deterministic_setup'] = parse_json_arg('deterministic_setup_json', (dict, list), None)
 
 # Generate branch if not provided. The riddle-proof/* namespace is reserved for
 # temporary proof worktrees, so never let a user-supplied branch use it as the
@@ -173,6 +197,16 @@ s['stage'] = 'preflight'
 s['status'] = 'ready' if not missing else 'needs_input'
 s['missing'] = missing
 
+if s.get('parent_proof_session') and not missing:
+    try:
+        s['proof_session_resume'] = {
+            **(s.get('proof_session_resume') or {}),
+            **validate_proof_session_resume(s, route=s.get('server_path') or ''),
+        }
+    except SystemExit:
+        save_state(s)
+        raise
+
 # Auth context can be supplied directly for public-plugin use, while use_auth
 # remains a private/configured Cognito helper for Riddle-owned environments.
 explicit_local_storage = parse_json_arg('auth_localStorage_json', (dict,), {})
@@ -231,7 +265,7 @@ print('RIDDLE PROOF — PREFLIGHT (' + mode.upper() + ' / ' + reference.upper()
 print('=' * 50)
 display_keys = ['repo', 'branch', 'target_branch', 'ship_target_branch', 'base_branch', 'before_ref', 'change_request', 'commit_message',
                 'reference', 'verification_mode', 'success_criteria', 'prod_url', 'build_command',
-                'allow_static_preview_fallback']
+                'allow_static_preview_fallback', 'resume_session', 'target_image_url', 'target_image_hash']
 if mode == 'server':
     display_keys += ['server_image', 'server_command', 'server_port', 'server_path']
 if s.get('auth_localStorage'):
@@ -247,6 +281,12 @@ for k in display_keys:
     print(k + ': ' + v)
 if parsed_assertions is not None:
     print('assertions_json: parsed')
+if s.get('viewport_matrix') is not None:
+    print('viewport_matrix_json: parsed')
+if s.get('deterministic_setup') is not None:
+    print('deterministic_setup_json: parsed')
+if s.get('proof_session_resume'):
+    print('proof_session_resume: ' + str((s.get('proof_session_resume') or {}).get('status') or 'loaded'))
 if not (s.get('capture_script') or '').strip():
     print('NOTE: capture_script can be added later after recon and before verify.')
 if reference_note: