@riddledc/riddle-proof 0.1.0

package/dist/types.d.cts

@@ -0,0 +1,179 @@
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+type JsonObject = {
+    [key: string]: JsonValue;
+};
+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" | "verify" | "ship" | (string & {});
+interface RiddleProofRunParams {
+    repo?: string;
+    branch?: string;
+    change_request?: string;
+    commit_message?: string;
+    prod_url?: string;
+    capture_script?: string;
+    success_criteria?: string;
+    assertions?: JsonValue;
+    verification_mode?: RiddleProofVerificationMode;
+    reference?: "prod" | "before" | "both";
+    base_branch?: string;
+    before_ref?: string;
+    allow_static_preview_fallback?: boolean;
+    context?: string;
+    reviewer?: string;
+    mode?: string;
+    build_command?: string;
+    build_output?: string;
+    server_image?: string;
+    server_command?: string;
+    server_port?: number;
+    server_path?: string;
+    use_auth?: boolean;
+    color_scheme?: "dark" | "light" | (string & {});
+    wait_for_selector?: string;
+    ship_mode?: "none" | "ship";
+    integration_context?: IntegrationContext;
+}
+interface IntegrationContext {
+    source?: "openclaw" | "discord" | "github" | "cli" | "riddle" | (string & {});
+    channel_id?: string;
+    thread_id?: string;
+    message_id?: string;
+    source_url?: string;
+    metadata?: Record<string, unknown>;
+}
+interface RiddleProofBlocker {
+    code: string;
+    message: string;
+    checkpoint?: string | null;
+    details?: Record<string, unknown>;
+}
+interface RiddleProofEvent {
+    ts: string;
+    kind: string;
+    checkpoint?: string | null;
+    stage?: RiddleProofStage | null;
+    summary?: string | null;
+    details?: Record<string, unknown>;
+}
+interface RiddleProofRunState {
+    version: "riddle-proof.run-state.v1";
+    state_path?: string;
+    status: RiddleProofStatus;
+    ok?: boolean;
+    created_at: string;
+    updated_at: string;
+    request: RiddleProofRunParams;
+    iterations: number;
+    last_checkpoint?: string | null;
+    pr_url?: string;
+    marked_ready?: boolean;
+    notification?: Record<string, unknown>;
+    proof_decision?: RiddleProofDecision;
+    merge_recommendation?: string;
+    finalized?: boolean;
+    blocker?: RiddleProofBlocker;
+    events: RiddleProofEvent[];
+}
+interface RiddleProofRunResult {
+    ok: boolean;
+    status: RiddleProofStatus;
+    state_path?: string | null;
+    iterations?: number;
+    last_checkpoint?: string | null;
+    last_summary?: string | null;
+    event_count?: number;
+    pr_url?: string;
+    marked_ready?: boolean;
+    notification?: Record<string, unknown>;
+    proof_decision?: RiddleProofDecision;
+    merge_recommendation?: string;
+    finalized?: boolean;
+    blocker?: RiddleProofBlocker;
+    evidence_bundle?: RiddleProofEvidenceBundle;
+    raw?: Record<string, unknown>;
+}
+interface RiddleProofEvidenceBundle {
+    verification_mode: RiddleProofVerificationMode;
+    baselines?: EvidenceReference[];
+    after?: EvidenceReference;
+    artifacts?: EvidenceArtifact[];
+    proof_evidence?: unknown;
+    proof_evidence_sample?: unknown;
+    assertions?: JsonValue;
+    summary?: string;
+    notes?: string[];
+}
+interface EvidenceReference {
+    kind: "before" | "prod" | "after" | "comparison" | (string & {});
+    url?: string;
+    path?: string;
+    observed_path?: string;
+    label?: string;
+    metadata?: Record<string, unknown>;
+}
+interface EvidenceArtifact {
+    name: string;
+    kind?: "screenshot" | "json" | "log" | "metric" | "audio" | "video" | (string & {});
+    url?: string;
+    path?: string;
+    content_type?: string;
+    size_bytes?: number;
+    metadata?: Record<string, unknown>;
+}
+interface RiddleProofAssessment {
+    decision: RiddleProofDecision;
+    summary: string;
+    recommended_stage?: RiddleProofStage;
+    continue_with_stage?: RiddleProofStage;
+    escalation_target?: "agent" | "human" | (string & {});
+    reasons?: string[];
+    source?: "supervising_agent" | "supervisor" | "human" | (string & {});
+}
+interface ImplementationAdapterInput {
+    workdir: string;
+    change_request: string;
+    evidence_context?: RiddleProofEvidenceBundle;
+    state?: RiddleProofRunState;
+}
+interface ImplementationAdapterResult {
+    ok: boolean;
+    changed_files?: string[];
+    implementation_notes?: string;
+    tests_run?: string[];
+    blockers?: string[];
+    raw?: Record<string, unknown>;
+}
+interface ImplementationAdapter {
+    implement(input: ImplementationAdapterInput): Promise<ImplementationAdapterResult>;
+}
+interface JudgeAdapter {
+    assessProof(input: {
+        state: RiddleProofRunState;
+        evidence_bundle: RiddleProofEvidenceBundle;
+    }): Promise<RiddleProofAssessment>;
+}
+interface ShipAdapter {
+    ship(input: {
+        state: RiddleProofRunState;
+        assessment: RiddleProofAssessment;
+    }): Promise<RiddleProofTerminalMetadata>;
+}
+interface NotificationAdapter {
+    notify(input: {
+        state: RiddleProofRunState;
+        result: RiddleProofRunResult;
+    }): Promise<Record<string, unknown>>;
+}
+interface RiddleProofTerminalMetadata {
+    pr_url?: string;
+    marked_ready?: boolean;
+    notification?: Record<string, unknown>;
+    proof_decision?: RiddleProofDecision;
+    merge_recommendation?: string;
+    finalized?: boolean;
+}
+
+export type { EvidenceArtifact, EvidenceReference, ImplementationAdapter, ImplementationAdapterInput, ImplementationAdapterResult, IntegrationContext, JsonObject, JsonPrimitive, JsonValue, JudgeAdapter, NotificationAdapter, RiddleProofAssessment, RiddleProofBlocker, RiddleProofDecision, RiddleProofEvent, RiddleProofEvidenceBundle, RiddleProofRunParams, RiddleProofRunResult, RiddleProofRunState, RiddleProofStage, RiddleProofStatus, RiddleProofTerminalMetadata, RiddleProofVerificationMode, ShipAdapter };

package/dist/types.d.ts

@@ -0,0 +1,179 @@
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+type JsonObject = {
+    [key: string]: JsonValue;
+};
+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" | "verify" | "ship" | (string & {});
+interface RiddleProofRunParams {
+    repo?: string;
+    branch?: string;
+    change_request?: string;
+    commit_message?: string;
+    prod_url?: string;
+    capture_script?: string;
+    success_criteria?: string;
+    assertions?: JsonValue;
+    verification_mode?: RiddleProofVerificationMode;
+    reference?: "prod" | "before" | "both";
+    base_branch?: string;
+    before_ref?: string;
+    allow_static_preview_fallback?: boolean;
+    context?: string;
+    reviewer?: string;
+    mode?: string;
+    build_command?: string;
+    build_output?: string;
+    server_image?: string;
+    server_command?: string;
+    server_port?: number;
+    server_path?: string;
+    use_auth?: boolean;
+    color_scheme?: "dark" | "light" | (string & {});
+    wait_for_selector?: string;
+    ship_mode?: "none" | "ship";
+    integration_context?: IntegrationContext;
+}
+interface IntegrationContext {
+    source?: "openclaw" | "discord" | "github" | "cli" | "riddle" | (string & {});
+    channel_id?: string;
+    thread_id?: string;
+    message_id?: string;
+    source_url?: string;
+    metadata?: Record<string, unknown>;
+}
+interface RiddleProofBlocker {
+    code: string;
+    message: string;
+    checkpoint?: string | null;
+    details?: Record<string, unknown>;
+}
+interface RiddleProofEvent {
+    ts: string;
+    kind: string;
+    checkpoint?: string | null;
+    stage?: RiddleProofStage | null;
+    summary?: string | null;
+    details?: Record<string, unknown>;
+}
+interface RiddleProofRunState {
+    version: "riddle-proof.run-state.v1";
+    state_path?: string;
+    status: RiddleProofStatus;
+    ok?: boolean;
+    created_at: string;
+    updated_at: string;
+    request: RiddleProofRunParams;
+    iterations: number;
+    last_checkpoint?: string | null;
+    pr_url?: string;
+    marked_ready?: boolean;
+    notification?: Record<string, unknown>;
+    proof_decision?: RiddleProofDecision;
+    merge_recommendation?: string;
+    finalized?: boolean;
+    blocker?: RiddleProofBlocker;
+    events: RiddleProofEvent[];
+}
+interface RiddleProofRunResult {
+    ok: boolean;
+    status: RiddleProofStatus;
+    state_path?: string | null;
+    iterations?: number;
+    last_checkpoint?: string | null;
+    last_summary?: string | null;
+    event_count?: number;
+    pr_url?: string;
+    marked_ready?: boolean;
+    notification?: Record<string, unknown>;
+    proof_decision?: RiddleProofDecision;
+    merge_recommendation?: string;
+    finalized?: boolean;
+    blocker?: RiddleProofBlocker;
+    evidence_bundle?: RiddleProofEvidenceBundle;
+    raw?: Record<string, unknown>;
+}
+interface RiddleProofEvidenceBundle {
+    verification_mode: RiddleProofVerificationMode;
+    baselines?: EvidenceReference[];
+    after?: EvidenceReference;
+    artifacts?: EvidenceArtifact[];
+    proof_evidence?: unknown;
+    proof_evidence_sample?: unknown;
+    assertions?: JsonValue;
+    summary?: string;
+    notes?: string[];
+}
+interface EvidenceReference {
+    kind: "before" | "prod" | "after" | "comparison" | (string & {});
+    url?: string;
+    path?: string;
+    observed_path?: string;
+    label?: string;
+    metadata?: Record<string, unknown>;
+}
+interface EvidenceArtifact {
+    name: string;
+    kind?: "screenshot" | "json" | "log" | "metric" | "audio" | "video" | (string & {});
+    url?: string;
+    path?: string;
+    content_type?: string;
+    size_bytes?: number;
+    metadata?: Record<string, unknown>;
+}
+interface RiddleProofAssessment {
+    decision: RiddleProofDecision;
+    summary: string;
+    recommended_stage?: RiddleProofStage;
+    continue_with_stage?: RiddleProofStage;
+    escalation_target?: "agent" | "human" | (string & {});
+    reasons?: string[];
+    source?: "supervising_agent" | "supervisor" | "human" | (string & {});
+}
+interface ImplementationAdapterInput {
+    workdir: string;
+    change_request: string;
+    evidence_context?: RiddleProofEvidenceBundle;
+    state?: RiddleProofRunState;
+}
+interface ImplementationAdapterResult {
+    ok: boolean;
+    changed_files?: string[];
+    implementation_notes?: string;
+    tests_run?: string[];
+    blockers?: string[];
+    raw?: Record<string, unknown>;
+}
+interface ImplementationAdapter {
+    implement(input: ImplementationAdapterInput): Promise<ImplementationAdapterResult>;
+}
+interface JudgeAdapter {
+    assessProof(input: {
+        state: RiddleProofRunState;
+        evidence_bundle: RiddleProofEvidenceBundle;
+    }): Promise<RiddleProofAssessment>;
+}
+interface ShipAdapter {
+    ship(input: {
+        state: RiddleProofRunState;
+        assessment: RiddleProofAssessment;
+    }): Promise<RiddleProofTerminalMetadata>;
+}
+interface NotificationAdapter {
+    notify(input: {
+        state: RiddleProofRunState;
+        result: RiddleProofRunResult;
+    }): Promise<Record<string, unknown>>;
+}
+interface RiddleProofTerminalMetadata {
+    pr_url?: string;
+    marked_ready?: boolean;
+    notification?: Record<string, unknown>;
+    proof_decision?: RiddleProofDecision;
+    merge_recommendation?: string;
+    finalized?: boolean;
+}
+
+export type { EvidenceArtifact, EvidenceReference, ImplementationAdapter, ImplementationAdapterInput, ImplementationAdapterResult, IntegrationContext, JsonObject, JsonPrimitive, JsonValue, JudgeAdapter, NotificationAdapter, RiddleProofAssessment, RiddleProofBlocker, RiddleProofDecision, RiddleProofEvent, RiddleProofEvidenceBundle, RiddleProofRunParams, RiddleProofRunResult, RiddleProofRunState, RiddleProofStage, RiddleProofStatus, RiddleProofTerminalMetadata, RiddleProofVerificationMode, ShipAdapter };

package/dist/types.js

@@ -0,0 +1 @@
+import "./chunk-6F4PWJZI.js";

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@riddledc/riddle-proof",
+  "version": "0.1.0",
+  "description": "Reusable Riddle Proof contracts and helpers for evidence-backed agent changes.",
+  "license": "MIT",
+  "author": "RiddleDC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/riddledc/integrations",
+    "directory": "packages/riddle-proof"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js",
+      "require": "./dist/types.cjs"
+    },
+    "./result": {
+      "types": "./dist/result.d.ts",
+      "import": "./dist/result.js",
+      "require": "./dist/result.cjs"
+    },
+    "./state": {
+      "types": "./dist/state.d.ts",
+      "import": "./dist/state.js",
+      "require": "./dist/state.cjs"
+    },
+    "./openclaw": {
+      "types": "./dist/openclaw.d.ts",
+      "import": "./dist/openclaw.js",
+      "require": "./dist/openclaw.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.4.5"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/types.ts src/result.ts src/state.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"
+  }
+}