@riddledc/riddle-proof 0.5.57 → 0.7.0

package/dist/profile.d.cts

@@ -0,0 +1,175 @@
+import { JsonValue } from './types.cjs';
+
+declare const RIDDLE_PROOF_PROFILE_VERSION: "riddle-proof.profile.v1";
+declare const RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION: "riddle-proof.profile-evidence.v1";
+declare const RIDDLE_PROOF_PROFILE_RESULT_VERSION: "riddle-proof.profile-result.v1";
+declare const RIDDLE_PROOF_PROFILE_STATUSES: readonly ["passed", "product_regression", "proof_insufficient", "environment_blocked", "configuration_error", "needs_human_review"];
+declare const RIDDLE_PROOF_PROFILE_CHECK_TYPES: readonly ["route_loaded", "selector_visible", "selector_count_at_least", "text_visible", "text_absent", "no_horizontal_overflow", "no_mobile_horizontal_overflow", "no_fatal_console_errors"];
+type RiddleProofProfileStatus = typeof RIDDLE_PROOF_PROFILE_STATUSES[number];
+type RiddleProofProfileCheckType = typeof RIDDLE_PROOF_PROFILE_CHECK_TYPES[number];
+type RiddleProofProfileRunner = "riddle" | "local-playwright" | "browserless" | "github-actions" | (string & {});
+type RiddleProofProfileFailureAction = "fail" | "neutral" | "review";
+type RiddleProofProfileBaselinePolicy = "invariant_only" | "production_comparison" | "last_accepted_artifact" | "golden_reference_artifact" | (string & {});
+interface RiddleProofProfileViewport {
+    name: string;
+    width: number;
+    height: number;
+}
+interface RiddleProofProfileTarget {
+    url?: string;
+    route?: string;
+    viewports: RiddleProofProfileViewport[];
+    auth?: "none" | (string & {});
+    wait_for_selector?: string;
+    wait_ms?: number;
+}
+interface RiddleProofProfileCheck {
+    type: RiddleProofProfileCheckType;
+    label?: string;
+    expected_path?: string;
+    selector?: string;
+    text?: string;
+    pattern?: string;
+    flags?: string;
+    min_count?: number;
+    max_overflow_px?: number;
+}
+interface RiddleProofProfile {
+    version: typeof RIDDLE_PROOF_PROFILE_VERSION;
+    name: string;
+    target: RiddleProofProfileTarget;
+    checks: RiddleProofProfileCheck[];
+    artifacts: string[];
+    baseline_policy: RiddleProofProfileBaselinePolicy;
+    failure_policy: Partial<Record<RiddleProofProfileStatus, RiddleProofProfileFailureAction>>;
+    metadata?: Record<string, JsonValue>;
+}
+interface RiddleProofProfileRouteEvidence {
+    requested: string;
+    observed: string;
+    expected_path?: string;
+    matched: boolean;
+    http_status?: number | null;
+    error?: string;
+}
+interface RiddleProofProfileViewportEvidence {
+    name: string;
+    width: number;
+    height: number;
+    url?: string;
+    route: RiddleProofProfileRouteEvidence;
+    title?: string;
+    body_text_length?: number;
+    body_text_sample?: string;
+    scroll_width?: number;
+    client_width?: number;
+    overflow_px?: number;
+    selectors?: Record<string, {
+        count: number;
+        visible_count: number;
+    }>;
+    text_matches?: Record<string, boolean>;
+    screenshot_label?: string;
+    navigation_error?: string;
+    wait_error?: string;
+}
+interface RiddleProofProfileEvidence {
+    version: typeof RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION;
+    profile_name: string;
+    target_url: string;
+    baseline_policy: RiddleProofProfileBaselinePolicy;
+    captured_at: string;
+    viewports: RiddleProofProfileViewportEvidence[];
+    console: {
+        events: Array<{
+            type: string;
+            text: string;
+            location?: JsonValue;
+        }>;
+        fatal_count: number;
+    };
+    page_errors: Array<{
+        message: string;
+    }>;
+    dom_summary?: Record<string, JsonValue>;
+}
+interface RiddleProofProfileCheckResult {
+    type: RiddleProofProfileCheckType | (string & {});
+    label?: string;
+    status: "passed" | "failed" | "skipped" | "needs_human_review";
+    evidence: Record<string, JsonValue>;
+    message?: string;
+}
+interface RiddleProofProfileResult {
+    version: typeof RIDDLE_PROOF_PROFILE_RESULT_VERSION;
+    profile_name: string;
+    runner: RiddleProofProfileRunner;
+    status: RiddleProofProfileStatus;
+    baseline_policy: RiddleProofProfileBaselinePolicy;
+    route: RiddleProofProfileRouteEvidence;
+    artifacts: {
+        screenshots: string[];
+        console?: string;
+        proof_json?: string;
+        dom_summary?: string;
+        riddle_artifacts?: RiddleProofProfileArtifactRef[];
+    };
+    checks: RiddleProofProfileCheckResult[];
+    summary: string;
+    captured_at: string;
+    evidence?: RiddleProofProfileEvidence;
+    riddle?: {
+        job_id?: string;
+        status?: string | null;
+        terminal?: boolean;
+    };
+    error?: string;
+}
+interface RiddleProofProfileArtifactRef {
+    name: string;
+    url?: string;
+    path?: string;
+    kind?: string;
+    content_type?: string;
+    source?: string;
+}
+interface NormalizeRiddleProofProfileOptions {
+    url?: string;
+    route?: string;
+    viewports?: RiddleProofProfileViewport[];
+}
+declare function slugifyRiddleProofProfileName(value: string): string;
+declare function normalizeRiddleProofProfile(input: unknown, options?: NormalizeRiddleProofProfileOptions): RiddleProofProfile;
+declare function resolveRiddleProofProfileTargetUrl(profile: RiddleProofProfile): string;
+declare function assessRiddleProofProfileEvidence(profile: RiddleProofProfile, evidence: RiddleProofProfileEvidence | undefined, options?: {
+    runner?: RiddleProofProfileRunner;
+    riddle?: RiddleProofProfileResult["riddle"];
+    artifacts?: RiddleProofProfileArtifactRef[];
+}): RiddleProofProfileResult;
+declare function summarizeRiddleProofProfileResult(input: {
+    profile_name: string;
+    status: RiddleProofProfileStatus;
+    checks: RiddleProofProfileCheckResult[];
+    viewports: RiddleProofProfileViewportEvidence[];
+}): string;
+declare function profileStatusExitCode(profile: RiddleProofProfile, status: RiddleProofProfileStatus): 0 | 1;
+declare function createRiddleProofProfileConfigurationError(name: string, error: unknown, runner?: RiddleProofProfileRunner): RiddleProofProfileResult;
+declare function createRiddleProofProfileEnvironmentBlockedResult(input: {
+    profile: RiddleProofProfile;
+    runner?: RiddleProofProfileRunner;
+    error?: unknown;
+    riddle?: RiddleProofProfileResult["riddle"];
+    artifacts?: RiddleProofProfileArtifactRef[];
+}): RiddleProofProfileResult;
+declare function createRiddleProofProfileInsufficientResult(input: {
+    profile: RiddleProofProfile;
+    runner?: RiddleProofProfileRunner;
+    error?: unknown;
+    riddle?: RiddleProofProfileResult["riddle"];
+    artifacts?: RiddleProofProfileArtifactRef[];
+}): RiddleProofProfileResult;
+declare function buildRiddleProofProfileScript(profile: RiddleProofProfile): string;
+declare function collectRiddleProfileArtifactRefs(input: unknown): RiddleProofProfileArtifactRef[];
+declare function extractRiddleProofProfileResult(input: unknown): RiddleProofProfileResult | undefined;
+
+export { type NormalizeRiddleProofProfileOptions, RIDDLE_PROOF_PROFILE_CHECK_TYPES, RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION, RIDDLE_PROOF_PROFILE_RESULT_VERSION, RIDDLE_PROOF_PROFILE_STATUSES, RIDDLE_PROOF_PROFILE_VERSION, type RiddleProofProfile, type RiddleProofProfileArtifactRef, type RiddleProofProfileBaselinePolicy, type RiddleProofProfileCheck, type RiddleProofProfileCheckResult, type RiddleProofProfileCheckType, type RiddleProofProfileEvidence, type RiddleProofProfileFailureAction, type RiddleProofProfileResult, type RiddleProofProfileRouteEvidence, type RiddleProofProfileRunner, type RiddleProofProfileStatus, type RiddleProofProfileTarget, type RiddleProofProfileViewport, type RiddleProofProfileViewportEvidence, assessRiddleProofProfileEvidence, buildRiddleProofProfileScript, collectRiddleProfileArtifactRefs, createRiddleProofProfileConfigurationError, createRiddleProofProfileEnvironmentBlockedResult, createRiddleProofProfileInsufficientResult, extractRiddleProofProfileResult, normalizeRiddleProofProfile, profileStatusExitCode, resolveRiddleProofProfileTargetUrl, slugifyRiddleProofProfileName, summarizeRiddleProofProfileResult };

package/dist/profile.d.ts

@@ -0,0 +1,175 @@
+import { JsonValue } from './types.js';
+
+declare const RIDDLE_PROOF_PROFILE_VERSION: "riddle-proof.profile.v1";
+declare const RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION: "riddle-proof.profile-evidence.v1";
+declare const RIDDLE_PROOF_PROFILE_RESULT_VERSION: "riddle-proof.profile-result.v1";
+declare const RIDDLE_PROOF_PROFILE_STATUSES: readonly ["passed", "product_regression", "proof_insufficient", "environment_blocked", "configuration_error", "needs_human_review"];
+declare const RIDDLE_PROOF_PROFILE_CHECK_TYPES: readonly ["route_loaded", "selector_visible", "selector_count_at_least", "text_visible", "text_absent", "no_horizontal_overflow", "no_mobile_horizontal_overflow", "no_fatal_console_errors"];
+type RiddleProofProfileStatus = typeof RIDDLE_PROOF_PROFILE_STATUSES[number];
+type RiddleProofProfileCheckType = typeof RIDDLE_PROOF_PROFILE_CHECK_TYPES[number];
+type RiddleProofProfileRunner = "riddle" | "local-playwright" | "browserless" | "github-actions" | (string & {});
+type RiddleProofProfileFailureAction = "fail" | "neutral" | "review";
+type RiddleProofProfileBaselinePolicy = "invariant_only" | "production_comparison" | "last_accepted_artifact" | "golden_reference_artifact" | (string & {});
+interface RiddleProofProfileViewport {
+    name: string;
+    width: number;
+    height: number;
+}
+interface RiddleProofProfileTarget {
+    url?: string;
+    route?: string;
+    viewports: RiddleProofProfileViewport[];
+    auth?: "none" | (string & {});
+    wait_for_selector?: string;
+    wait_ms?: number;
+}
+interface RiddleProofProfileCheck {
+    type: RiddleProofProfileCheckType;
+    label?: string;
+    expected_path?: string;
+    selector?: string;
+    text?: string;
+    pattern?: string;
+    flags?: string;
+    min_count?: number;
+    max_overflow_px?: number;
+}
+interface RiddleProofProfile {
+    version: typeof RIDDLE_PROOF_PROFILE_VERSION;
+    name: string;
+    target: RiddleProofProfileTarget;
+    checks: RiddleProofProfileCheck[];
+    artifacts: string[];
+    baseline_policy: RiddleProofProfileBaselinePolicy;
+    failure_policy: Partial<Record<RiddleProofProfileStatus, RiddleProofProfileFailureAction>>;
+    metadata?: Record<string, JsonValue>;
+}
+interface RiddleProofProfileRouteEvidence {
+    requested: string;
+    observed: string;
+    expected_path?: string;
+    matched: boolean;
+    http_status?: number | null;
+    error?: string;
+}
+interface RiddleProofProfileViewportEvidence {
+    name: string;
+    width: number;
+    height: number;
+    url?: string;
+    route: RiddleProofProfileRouteEvidence;
+    title?: string;
+    body_text_length?: number;
+    body_text_sample?: string;
+    scroll_width?: number;
+    client_width?: number;
+    overflow_px?: number;
+    selectors?: Record<string, {
+        count: number;
+        visible_count: number;
+    }>;
+    text_matches?: Record<string, boolean>;
+    screenshot_label?: string;
+    navigation_error?: string;
+    wait_error?: string;
+}
+interface RiddleProofProfileEvidence {
+    version: typeof RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION;
+    profile_name: string;
+    target_url: string;
+    baseline_policy: RiddleProofProfileBaselinePolicy;
+    captured_at: string;
+    viewports: RiddleProofProfileViewportEvidence[];
+    console: {
+        events: Array<{
+            type: string;
+            text: string;
+            location?: JsonValue;
+        }>;
+        fatal_count: number;
+    };
+    page_errors: Array<{
+        message: string;
+    }>;
+    dom_summary?: Record<string, JsonValue>;
+}
+interface RiddleProofProfileCheckResult {
+    type: RiddleProofProfileCheckType | (string & {});
+    label?: string;
+    status: "passed" | "failed" | "skipped" | "needs_human_review";
+    evidence: Record<string, JsonValue>;
+    message?: string;
+}
+interface RiddleProofProfileResult {
+    version: typeof RIDDLE_PROOF_PROFILE_RESULT_VERSION;
+    profile_name: string;
+    runner: RiddleProofProfileRunner;
+    status: RiddleProofProfileStatus;
+    baseline_policy: RiddleProofProfileBaselinePolicy;
+    route: RiddleProofProfileRouteEvidence;
+    artifacts: {
+        screenshots: string[];
+        console?: string;
+        proof_json?: string;
+        dom_summary?: string;
+        riddle_artifacts?: RiddleProofProfileArtifactRef[];
+    };
+    checks: RiddleProofProfileCheckResult[];
+    summary: string;
+    captured_at: string;
+    evidence?: RiddleProofProfileEvidence;
+    riddle?: {
+        job_id?: string;
+        status?: string | null;
+        terminal?: boolean;
+    };
+    error?: string;
+}
+interface RiddleProofProfileArtifactRef {
+    name: string;
+    url?: string;
+    path?: string;
+    kind?: string;
+    content_type?: string;
+    source?: string;
+}
+interface NormalizeRiddleProofProfileOptions {
+    url?: string;
+    route?: string;
+    viewports?: RiddleProofProfileViewport[];
+}
+declare function slugifyRiddleProofProfileName(value: string): string;
+declare function normalizeRiddleProofProfile(input: unknown, options?: NormalizeRiddleProofProfileOptions): RiddleProofProfile;
+declare function resolveRiddleProofProfileTargetUrl(profile: RiddleProofProfile): string;
+declare function assessRiddleProofProfileEvidence(profile: RiddleProofProfile, evidence: RiddleProofProfileEvidence | undefined, options?: {
+    runner?: RiddleProofProfileRunner;
+    riddle?: RiddleProofProfileResult["riddle"];
+    artifacts?: RiddleProofProfileArtifactRef[];
+}): RiddleProofProfileResult;
+declare function summarizeRiddleProofProfileResult(input: {
+    profile_name: string;
+    status: RiddleProofProfileStatus;
+    checks: RiddleProofProfileCheckResult[];
+    viewports: RiddleProofProfileViewportEvidence[];
+}): string;
+declare function profileStatusExitCode(profile: RiddleProofProfile, status: RiddleProofProfileStatus): 0 | 1;
+declare function createRiddleProofProfileConfigurationError(name: string, error: unknown, runner?: RiddleProofProfileRunner): RiddleProofProfileResult;
+declare function createRiddleProofProfileEnvironmentBlockedResult(input: {
+    profile: RiddleProofProfile;
+    runner?: RiddleProofProfileRunner;
+    error?: unknown;
+    riddle?: RiddleProofProfileResult["riddle"];
+    artifacts?: RiddleProofProfileArtifactRef[];
+}): RiddleProofProfileResult;
+declare function createRiddleProofProfileInsufficientResult(input: {
+    profile: RiddleProofProfile;
+    runner?: RiddleProofProfileRunner;
+    error?: unknown;
+    riddle?: RiddleProofProfileResult["riddle"];
+    artifacts?: RiddleProofProfileArtifactRef[];
+}): RiddleProofProfileResult;
+declare function buildRiddleProofProfileScript(profile: RiddleProofProfile): string;
+declare function collectRiddleProfileArtifactRefs(input: unknown): RiddleProofProfileArtifactRef[];
+declare function extractRiddleProofProfileResult(input: unknown): RiddleProofProfileResult | undefined;
+
+export { type NormalizeRiddleProofProfileOptions, RIDDLE_PROOF_PROFILE_CHECK_TYPES, RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION, RIDDLE_PROOF_PROFILE_RESULT_VERSION, RIDDLE_PROOF_PROFILE_STATUSES, RIDDLE_PROOF_PROFILE_VERSION, type RiddleProofProfile, type RiddleProofProfileArtifactRef, type RiddleProofProfileBaselinePolicy, type RiddleProofProfileCheck, type RiddleProofProfileCheckResult, type RiddleProofProfileCheckType, type RiddleProofProfileEvidence, type RiddleProofProfileFailureAction, type RiddleProofProfileResult, type RiddleProofProfileRouteEvidence, type RiddleProofProfileRunner, type RiddleProofProfileStatus, type RiddleProofProfileTarget, type RiddleProofProfileViewport, type RiddleProofProfileViewportEvidence, assessRiddleProofProfileEvidence, buildRiddleProofProfileScript, collectRiddleProfileArtifactRefs, createRiddleProofProfileConfigurationError, createRiddleProofProfileEnvironmentBlockedResult, createRiddleProofProfileInsufficientResult, extractRiddleProofProfileResult, normalizeRiddleProofProfile, profileStatusExitCode, resolveRiddleProofProfileTargetUrl, slugifyRiddleProofProfileName, summarizeRiddleProofProfileResult };

package/dist/profile.js

@@ -0,0 +1,38 @@
+import {
+  RIDDLE_PROOF_PROFILE_CHECK_TYPES,
+  RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION,
+  RIDDLE_PROOF_PROFILE_RESULT_VERSION,
+  RIDDLE_PROOF_PROFILE_STATUSES,
+  RIDDLE_PROOF_PROFILE_VERSION,
+  assessRiddleProofProfileEvidence,
+  buildRiddleProofProfileScript,
+  collectRiddleProfileArtifactRefs,
+  createRiddleProofProfileConfigurationError,
+  createRiddleProofProfileEnvironmentBlockedResult,
+  createRiddleProofProfileInsufficientResult,
+  extractRiddleProofProfileResult,
+  normalizeRiddleProofProfile,
+  profileStatusExitCode,
+  resolveRiddleProofProfileTargetUrl,
+  slugifyRiddleProofProfileName,
+  summarizeRiddleProofProfileResult
+} from "./chunk-7NMAU4DP.js";
+export {
+  RIDDLE_PROOF_PROFILE_CHECK_TYPES,
+  RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION,
+  RIDDLE_PROOF_PROFILE_RESULT_VERSION,
+  RIDDLE_PROOF_PROFILE_STATUSES,
+  RIDDLE_PROOF_PROFILE_VERSION,
+  assessRiddleProofProfileEvidence,
+  buildRiddleProofProfileScript,
+  collectRiddleProfileArtifactRefs,
+  createRiddleProofProfileConfigurationError,
+  createRiddleProofProfileEnvironmentBlockedResult,
+  createRiddleProofProfileInsufficientResult,
+  extractRiddleProofProfileResult,
+  normalizeRiddleProofProfile,
+  profileStatusExitCode,
+  resolveRiddleProofProfileTargetUrl,
+  slugifyRiddleProofProfileName,
+  summarizeRiddleProofProfileResult
+};

package/examples/profiles/page-content-basic.json

@@ -0,0 +1,26 @@
+{
+  "version": "riddle-proof.profile.v1",
+  "name": "page-content-basic",
+  "target": {
+    "route": "/",
+    "viewports": [
+      { "name": "mobile", "width": 390, "height": 844 },
+      { "name": "desktop", "width": 1440, "height": 1000 }
+    ],
+    "auth": "none",
+    "wait_for_selector": "body"
+  },
+  "checks": [
+    { "type": "route_loaded", "expected_path": "/" },
+    { "type": "selector_visible", "selector": "body" },
+    { "type": "text_visible", "text": "Example" },
+    { "type": "no_mobile_horizontal_overflow" },
+    { "type": "no_fatal_console_errors" }
+  ],
+  "artifacts": ["screenshot", "console", "dom_summary", "proof_json"],
+  "failure_policy": {
+    "environment_blocked": "neutral",
+    "proof_insufficient": "fail",
+    "product_regression": "fail"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riddledc/riddle-proof",
-  "version": "0.5.57",
+  "version": "0.7.0",
   "description": "Reusable Riddle Proof contracts and helpers for evidence-backed agent changes.",
   "license": "MIT",
   "author": "RiddleDC",
@@ -84,6 +84,11 @@
       "import": "./dist/basic-gameplay.js",
       "require": "./dist/basic-gameplay.cjs"
     },
+    "./profile": {
+      "types": "./dist/profile.d.ts",
+      "import": "./dist/profile.js",
+      "require": "./dist/profile.cjs"
+    },
     "./openclaw": {
       "types": "./dist/openclaw.d.ts",
       "import": "./dist/openclaw.js",
@@ -110,6 +115,7 @@
   },
   "files": [
     "dist",
+    "examples",
     "lib",
     "runtime",
     "README.md",
@@ -125,7 +131,7 @@
     "typescript": "^5.4.5"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/types.ts src/result.ts src/state.ts src/checkpoint.ts src/run-card.ts src/runner.ts src/engine-harness.ts src/codex-exec-agent.ts src/local-agent.ts src/cli.ts src/diagnostics.ts src/proof-session.ts src/playability.ts src/basic-gameplay.ts src/openclaw.ts src/proof-run-core.ts src/proof-run-engine.ts src/riddle-client.ts --format cjs,esm --dts --out-dir dist --clean",
+    "build": "tsup src/index.ts src/types.ts src/result.ts src/state.ts src/checkpoint.ts src/run-card.ts src/runner.ts src/engine-harness.ts src/codex-exec-agent.ts src/local-agent.ts src/cli.ts src/diagnostics.ts src/proof-session.ts src/playability.ts src/basic-gameplay.ts src/profile.ts src/openclaw.ts src/proof-run-core.ts src/proof-run-engine.ts src/riddle-client.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"