@riddledc/riddle-proof 0.5.36 → 0.5.38

package/dist/playability.cjs

@@ -0,0 +1,389 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/playability.ts
+var playability_exports = {};
+__export(playability_exports, {
+  RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION: () => RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION,
+  RIDDLE_PROOF_PLAYABILITY_VERSION: () => RIDDLE_PROOF_PLAYABILITY_VERSION,
+  assessPlayabilityEvidence: () => assessPlayabilityEvidence,
+  extractPlayabilityEvidence: () => extractPlayabilityEvidence,
+  isRiddleProofPlayabilityMode: () => isRiddleProofPlayabilityMode
+});
+module.exports = __toCommonJS(playability_exports);
+var RIDDLE_PROOF_PLAYABILITY_VERSION = "riddle-proof.playability.v1";
+var RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION = "riddle-proof.playability.assessment.v1";
+var PLAYABILITY_MODES = /* @__PURE__ */ new Set(["playable", "gameplay", "game"]);
+var PLAYABILITY_CONTAINER_KEYS = [
+  "playability",
+  "playability_evidence",
+  "playabilityEvidence",
+  "playable",
+  "gameplay",
+  "gameplay_evidence",
+  "gameplayEvidence"
+];
+var INPUT_ASSERTION_KEYS = [
+  "inputAccepted",
+  "inputObserved",
+  "inputReceived",
+  "controlsWorked",
+  "keyboardWorked",
+  "pointerWorked",
+  "touchWorked",
+  "steeringInputAccepted",
+  "userInputObserved"
+];
+var STATE_ASSERTION_KEYS = [
+  "stateChanged",
+  "gameStateChanged",
+  "playStarted",
+  "simulationAdvanced",
+  "distanceAdvanced",
+  "scoreChanged",
+  "hudChanged",
+  "positionChanged",
+  "speedChanged"
+];
+var MOTION_ASSERTION_KEYS = [
+  "motionObserved",
+  "visualMotion",
+  "canvasChanged",
+  "pixelChanged",
+  "playfieldMoved",
+  "playfieldPixelsChanged",
+  "nonHudPixelsChanged",
+  "animationAdvanced",
+  "frameChanged",
+  "framesChanged"
+];
+var TIME_ASSERTION_KEYS = [
+  "timeProgressed",
+  "clockAdvanced",
+  "animationAdvanced",
+  "simulationAdvanced",
+  "playStarted"
+];
+var PERCENT_KEYS = [
+  "changed_percent",
+  "change_percent",
+  "percent_changed",
+  "diff_percent",
+  "motion_percent",
+  "pixel_change_percent"
+];
+var RATIO_KEYS = [
+  "changed_ratio",
+  "change_ratio",
+  "diff_ratio",
+  "motion_ratio",
+  "pixel_change_ratio"
+];
+var PIXEL_KEYS = [
+  "changed_pixels",
+  "changed_pixel_count",
+  "diff_pixels",
+  "motion_pixels",
+  "pixel_delta",
+  "changedPixels"
+];
+var AVERAGE_DELTA_KEYS = [
+  "average_delta",
+  "avg_delta",
+  "mean_delta",
+  "avg_abs_delta",
+  "mean_abs_delta"
+];
+var TIME_DELTA_KEYS = [
+  "time_delta_ms",
+  "elapsed_ms",
+  "duration_ms",
+  "sample_duration_ms",
+  "animation_delta_ms"
+];
+function isRiddleProofPlayabilityMode(mode) {
+  return PLAYABILITY_MODES.has(stringValue(mode).toLowerCase());
+}
+function extractPlayabilityEvidence(...sources) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const source of sources) {
+    const found = findPlayabilityEvidence(source, seen);
+    if (found) return found;
+  }
+  return null;
+}
+function assessPlayabilityEvidence(evidence, options = {}) {
+  const thresholds = {
+    minChangedPercent: options.minChangedPercent ?? 0.5,
+    minChangedPixels: options.minChangedPixels ?? 1e3,
+    minAverageDelta: options.minAverageDelta ?? 1,
+    minTimeDeltaMs: options.minTimeDeltaMs ?? 250
+  };
+  const required = {
+    requireInput: options.requireInput ?? true,
+    requireStateChange: options.requireStateChange ?? true,
+    requireMotion: options.requireMotion ?? true,
+    requireTimeProgression: options.requireTimeProgression ?? true
+  };
+  const record = extractPlayabilityEvidence(evidence);
+  const metrics = {};
+  const concerns = [];
+  if (!record) {
+    return {
+      version: RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION,
+      evidence_present: false,
+      passed: false,
+      input_observed: false,
+      state_changed: false,
+      motion_observed: false,
+      time_progressed: false,
+      concerns: ["playability evidence is missing"],
+      metrics,
+      thresholds,
+      required,
+      evidence_keys: []
+    };
+  }
+  const assertions = recordValue(record.assertions) || record;
+  const inputObserved = inputObservedFrom(record, assertions);
+  const stateChanged = stateChangedFrom(record, assertions, metrics);
+  const motionObserved = motionObservedFrom(record, assertions, thresholds, metrics);
+  const timeProgressed = timeProgressedFrom(record, assertions, thresholds, metrics);
+  const explicitFailure = hasExplicitPlayabilityFailure(record, assertions);
+  if (required.requireInput && !inputObserved) {
+    concerns.push("no accepted player input was observed");
+  }
+  if (required.requireStateChange && !stateChanged) {
+    concerns.push("game state did not measurably change");
+  }
+  if (required.requireMotion && !motionObserved) {
+    concerns.push("playfield/canvas pixels did not measurably change");
+  }
+  if (required.requireTimeProgression && !timeProgressed) {
+    concerns.push("play time or animation time did not measurably progress");
+  }
+  if (explicitFailure) {
+    concerns.push("playability evidence includes an explicit failed assertion");
+  }
+  const passed = Boolean(
+    (!required.requireInput || inputObserved) && (!required.requireStateChange || stateChanged) && (!required.requireMotion || motionObserved) && (!required.requireTimeProgression || timeProgressed) && !explicitFailure
+  );
+  return {
+    version: RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION,
+    evidence_present: true,
+    passed,
+    input_observed: inputObserved,
+    state_changed: stateChanged,
+    motion_observed: motionObserved,
+    time_progressed: timeProgressed,
+    concerns,
+    metrics,
+    thresholds,
+    required,
+    evidence_keys: Object.keys(record)
+  };
+}
+function findPlayabilityEvidence(value, seen, depth = 0) {
+  if (depth > 6 || value === null || value === void 0) return null;
+  if (typeof value === "string") {
+    const parsed = parseJson(value);
+    return parsed === null ? null : findPlayabilityEvidence(parsed, seen, depth + 1);
+  }
+  if (Array.isArray(value)) {
+    if (seen.has(value)) return null;
+    seen.add(value);
+    for (const item of value) {
+      const found = findPlayabilityEvidence(item, seen, depth + 1);
+      if (found) return found;
+    }
+    return null;
+  }
+  const record = recordValue(value);
+  if (!record || seen.has(record)) return null;
+  seen.add(record);
+  if (record.version === RIDDLE_PROOF_PLAYABILITY_VERSION || hasPlayabilityShape(record)) {
+    return record;
+  }
+  for (const key of PLAYABILITY_CONTAINER_KEYS) {
+    if (Object.prototype.hasOwnProperty.call(record, key)) {
+      const nested = findPlayabilityEvidence(record[key], seen, depth + 1);
+      if (nested) return nested;
+      if (typeof record[key] === "boolean") {
+        return { assertions: { [key]: record[key] } };
+      }
+    }
+  }
+  for (const item of Object.values(record)) {
+    const found = findPlayabilityEvidence(item, seen, depth + 1);
+    if (found) return found;
+  }
+  return null;
+}
+function hasPlayabilityShape(record) {
+  return Boolean(
+    record.input_events || record.state_delta || record.pixel_delta || record.canvas_delta || record.motion_delta || record.playfield_delta || record.time_delta_ms !== void 0 || hasAnyKey(recordValue(record.assertions) || record, [
+      ...INPUT_ASSERTION_KEYS,
+      ...STATE_ASSERTION_KEYS,
+      ...MOTION_ASSERTION_KEYS,
+      ...TIME_ASSERTION_KEYS
+    ])
+  );
+}
+function inputObservedFrom(record, assertions) {
+  if (trueForAnyKey(assertions, INPUT_ASSERTION_KEYS)) return true;
+  if (listValue(record.input_events).length > 0) return true;
+  if (listValue(record.inputs).length > 0) return true;
+  if (listValue(record.interactions).length > 0) return true;
+  const eventCount = numericFromAnyKey(record, ["input_event_count", "input_count", "interaction_count"]);
+  return eventCount !== null && eventCount > 0;
+}
+function stateChangedFrom(record, assertions, metrics) {
+  if (trueForAnyKey(assertions, STATE_ASSERTION_KEYS)) return true;
+  const stateDelta = recordValue(record.state_delta) || recordValue(record.stateDelta);
+  if (stateDelta) {
+    const changedKeys = listValue(stateDelta.changed_keys || stateDelta.changedKeys);
+    metrics.state_changed_keys = changedKeys;
+    if (stateDelta.changed === true || changedKeys.length > 0) return true;
+  }
+  const delta = numericFromAnyKey(record, [
+    "distance_delta",
+    "score_delta",
+    "position_delta",
+    "speed_delta",
+    "hud_delta"
+  ]);
+  if (delta !== null) {
+    metrics.state_numeric_delta = delta;
+    return Math.abs(delta) > 0;
+  }
+  return false;
+}
+function motionObservedFrom(record, assertions, thresholds, metrics) {
+  if (trueForAnyKey(assertions, MOTION_ASSERTION_KEYS)) return true;
+  for (const source of [
+    recordValue(record.playfield_delta),
+    recordValue(record.playfieldDelta),
+    recordValue(record.non_hud_delta),
+    recordValue(record.nonHudDelta),
+    recordValue(record.pixel_delta),
+    recordValue(record.pixelDelta),
+    recordValue(record.canvas_delta),
+    recordValue(record.canvasDelta),
+    recordValue(record.motion_delta),
+    recordValue(record.motionDelta),
+    recordValue(record.visual_delta),
+    recordValue(record.visualDelta),
+    record
+  ]) {
+    if (!source) continue;
+    const percent = percentFrom(source);
+    const pixels = numericFromAnyKey(source, PIXEL_KEYS);
+    const averageDelta = numericFromAnyKey(source, AVERAGE_DELTA_KEYS);
+    if (percent !== null) metrics.changed_percent = percent;
+    if (pixels !== null) metrics.changed_pixels = pixels;
+    if (averageDelta !== null) metrics.average_delta = averageDelta;
+    if (percent !== null && percent >= thresholds.minChangedPercent) return true;
+    if (pixels !== null && pixels >= thresholds.minChangedPixels) return true;
+    if (averageDelta !== null && averageDelta >= thresholds.minAverageDelta) return true;
+  }
+  return false;
+}
+function timeProgressedFrom(record, assertions, thresholds, metrics) {
+  if (trueForAnyKey(assertions, TIME_ASSERTION_KEYS)) return true;
+  const timeDelta = numericFromAnyKey(record, TIME_DELTA_KEYS);
+  if (timeDelta !== null) {
+    metrics.time_delta_ms = timeDelta;
+    return timeDelta >= thresholds.minTimeDeltaMs;
+  }
+  const stateDelta = recordValue(record.state_delta) || recordValue(record.stateDelta);
+  const nestedDelta = numericFromAnyKey(stateDelta || {}, TIME_DELTA_KEYS);
+  if (nestedDelta !== null) {
+    metrics.time_delta_ms = nestedDelta;
+    return nestedDelta >= thresholds.minTimeDeltaMs;
+  }
+  return false;
+}
+function hasExplicitPlayabilityFailure(record, assertions) {
+  if (record.passed === false || record.playable === false || assertions.playabilityPassed === false) {
+    return true;
+  }
+  for (const key of [
+    ...INPUT_ASSERTION_KEYS,
+    ...STATE_ASSERTION_KEYS,
+    ...MOTION_ASSERTION_KEYS,
+    ...TIME_ASSERTION_KEYS
+  ]) {
+    if (assertions[key] === false) return true;
+  }
+  return false;
+}
+function trueForAnyKey(record, keys) {
+  return keys.some((key) => record[key] === true);
+}
+function hasAnyKey(record, keys) {
+  return keys.some((key) => Object.prototype.hasOwnProperty.call(record, key));
+}
+function percentFrom(record) {
+  const percent = numericFromAnyKey(record, PERCENT_KEYS);
+  if (percent !== null) return percent;
+  const ratio = numericFromAnyKey(record, RATIO_KEYS);
+  if (ratio !== null) return ratio <= 1 ? ratio * 100 : ratio;
+  return null;
+}
+function numericFromAnyKey(record, keys) {
+  for (const key of keys) {
+    const value = numericValue(record[key]);
+    if (value !== null) return value;
+  }
+  return null;
+}
+function recordValue(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function listValue(value) {
+  return Array.isArray(value) ? value : [];
+}
+function numericValue(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+function stringValue(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : "";
+}
+function parseJson(value) {
+  const trimmed = value.trim();
+  if (!trimmed || !/^[{[]/.test(trimmed)) return null;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION,
+  RIDDLE_PROOF_PLAYABILITY_VERSION,
+  assessPlayabilityEvidence,
+  extractPlayabilityEvidence,
+  isRiddleProofPlayabilityMode
+});

package/dist/playability.d.cts

@@ -0,0 +1,44 @@
+declare const RIDDLE_PROOF_PLAYABILITY_VERSION = "riddle-proof.playability.v1";
+declare const RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION = "riddle-proof.playability.assessment.v1";
+interface RiddleProofPlayabilityEvidence {
+    version?: typeof RIDDLE_PROOF_PLAYABILITY_VERSION | string;
+    target?: string;
+    input_events?: unknown[];
+    state_delta?: Record<string, unknown>;
+    pixel_delta?: Record<string, unknown>;
+    canvas_delta?: Record<string, unknown>;
+    motion_delta?: Record<string, unknown>;
+    playfield_delta?: Record<string, unknown>;
+    time_delta_ms?: number;
+    assertions?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface AssessPlayabilityOptions {
+    minChangedPercent?: number;
+    minChangedPixels?: number;
+    minAverageDelta?: number;
+    minTimeDeltaMs?: number;
+    requireInput?: boolean;
+    requireStateChange?: boolean;
+    requireMotion?: boolean;
+    requireTimeProgression?: boolean;
+}
+interface RiddleProofPlayabilityAssessment {
+    version: typeof RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION;
+    evidence_present: boolean;
+    passed: boolean;
+    input_observed: boolean;
+    state_changed: boolean;
+    motion_observed: boolean;
+    time_progressed: boolean;
+    concerns: string[];
+    metrics: Record<string, unknown>;
+    thresholds: Required<Pick<AssessPlayabilityOptions, "minChangedPercent" | "minChangedPixels" | "minAverageDelta" | "minTimeDeltaMs">>;
+    required: Required<Pick<AssessPlayabilityOptions, "requireInput" | "requireStateChange" | "requireMotion" | "requireTimeProgression">>;
+    evidence_keys: string[];
+}
+declare function isRiddleProofPlayabilityMode(mode: unknown): boolean;
+declare function extractPlayabilityEvidence(...sources: unknown[]): RiddleProofPlayabilityEvidence | null;
+declare function assessPlayabilityEvidence(evidence: unknown, options?: AssessPlayabilityOptions): RiddleProofPlayabilityAssessment;
+
+export { type AssessPlayabilityOptions, RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION, RIDDLE_PROOF_PLAYABILITY_VERSION, type RiddleProofPlayabilityAssessment, type RiddleProofPlayabilityEvidence, assessPlayabilityEvidence, extractPlayabilityEvidence, isRiddleProofPlayabilityMode };

package/dist/playability.d.ts

@@ -0,0 +1,44 @@
+declare const RIDDLE_PROOF_PLAYABILITY_VERSION = "riddle-proof.playability.v1";
+declare const RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION = "riddle-proof.playability.assessment.v1";
+interface RiddleProofPlayabilityEvidence {
+    version?: typeof RIDDLE_PROOF_PLAYABILITY_VERSION | string;
+    target?: string;
+    input_events?: unknown[];
+    state_delta?: Record<string, unknown>;
+    pixel_delta?: Record<string, unknown>;
+    canvas_delta?: Record<string, unknown>;
+    motion_delta?: Record<string, unknown>;
+    playfield_delta?: Record<string, unknown>;
+    time_delta_ms?: number;
+    assertions?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface AssessPlayabilityOptions {
+    minChangedPercent?: number;
+    minChangedPixels?: number;
+    minAverageDelta?: number;
+    minTimeDeltaMs?: number;
+    requireInput?: boolean;
+    requireStateChange?: boolean;
+    requireMotion?: boolean;
+    requireTimeProgression?: boolean;
+}
+interface RiddleProofPlayabilityAssessment {
+    version: typeof RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION;
+    evidence_present: boolean;
+    passed: boolean;
+    input_observed: boolean;
+    state_changed: boolean;
+    motion_observed: boolean;
+    time_progressed: boolean;
+    concerns: string[];
+    metrics: Record<string, unknown>;
+    thresholds: Required<Pick<AssessPlayabilityOptions, "minChangedPercent" | "minChangedPixels" | "minAverageDelta" | "minTimeDeltaMs">>;
+    required: Required<Pick<AssessPlayabilityOptions, "requireInput" | "requireStateChange" | "requireMotion" | "requireTimeProgression">>;
+    evidence_keys: string[];
+}
+declare function isRiddleProofPlayabilityMode(mode: unknown): boolean;
+declare function extractPlayabilityEvidence(...sources: unknown[]): RiddleProofPlayabilityEvidence | null;
+declare function assessPlayabilityEvidence(evidence: unknown, options?: AssessPlayabilityOptions): RiddleProofPlayabilityAssessment;
+
+export { type AssessPlayabilityOptions, RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION, RIDDLE_PROOF_PLAYABILITY_VERSION, type RiddleProofPlayabilityAssessment, type RiddleProofPlayabilityEvidence, assessPlayabilityEvidence, extractPlayabilityEvidence, isRiddleProofPlayabilityMode };

package/dist/playability.js

@@ -0,0 +1,14 @@
+import {
+  RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION,
+  RIDDLE_PROOF_PLAYABILITY_VERSION,
+  assessPlayabilityEvidence,
+  extractPlayabilityEvidence,
+  isRiddleProofPlayabilityMode
+} from "./chunk-NSWT3VSV.js";
+export {
+  RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION,
+  RIDDLE_PROOF_PLAYABILITY_VERSION,
+  assessPlayabilityEvidence,
+  extractPlayabilityEvidence,
+  isRiddleProofPlayabilityMode
+};

package/dist/types.d.cts

@@ -5,7 +5,7 @@ type JsonObject = {
 };
 type RiddleProofStatus = "running" | "blocked" | "failed" | "ready_to_ship" | "shipped" | "completed";
 type RiddleProofPrLifecycleStatus = "unknown" | "open" | "merged" | "closed" | "not_found" | "unavailable" | (string & {});
-type RiddleProofVerificationMode = "proof" | "visual" | "interaction" | "render" | "data" | "json" | "audio" | "log" | "logs" | "metric" | "metrics" | (string & {});
+type RiddleProofVerificationMode = "proof" | "visual" | "interaction" | "playable" | "gameplay" | "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 = "preflight" | "setup" | "recon" | "author" | "implement" | "prove" | "verify" | "ship" | "notify" | (string & {});
 type RiddleProofArtifactRole = "baseline" | "after_proof" | "incidental" | "diagnostic" | (string & {});
@@ -188,6 +188,7 @@ interface RiddleProofEvidenceBundle {
     artifacts?: EvidenceArtifact[];
     proof_session?: RiddleProofVisualSession;
     proof_evidence?: unknown;
+    playability_evidence?: unknown;
     proof_evidence_sample?: unknown;
     assertions?: JsonValue;
     semantic_context?: Record<string, unknown>;

package/dist/types.d.ts

@@ -5,7 +5,7 @@ type JsonObject = {
 };
 type RiddleProofStatus = "running" | "blocked" | "failed" | "ready_to_ship" | "shipped" | "completed";
 type RiddleProofPrLifecycleStatus = "unknown" | "open" | "merged" | "closed" | "not_found" | "unavailable" | (string & {});
-type RiddleProofVerificationMode = "proof" | "visual" | "interaction" | "render" | "data" | "json" | "audio" | "log" | "logs" | "metric" | "metrics" | (string & {});
+type RiddleProofVerificationMode = "proof" | "visual" | "interaction" | "playable" | "gameplay" | "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 = "preflight" | "setup" | "recon" | "author" | "implement" | "prove" | "verify" | "ship" | "notify" | (string & {});
 type RiddleProofArtifactRole = "baseline" | "after_proof" | "incidental" | "diagnostic" | (string & {});
@@ -188,6 +188,7 @@ interface RiddleProofEvidenceBundle {
     artifacts?: EvidenceArtifact[];
     proof_session?: RiddleProofVisualSession;
     proof_evidence?: unknown;
+    playability_evidence?: unknown;
     proof_evidence_sample?: unknown;
     assertions?: JsonValue;
     semantic_context?: Record<string, unknown>;

package/lib/workspace-core.mjs

@@ -15,6 +15,8 @@ import {
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+const DEFAULT_RIDDLE_PROOF_SCRATCH_ROOT = "/var/tmp/riddle-proof";
+
 function commandEnv() {
   return { ...process.env, HOME: "/root" };
 }
@@ -58,6 +60,26 @@ export function uniqueToken(now = new Date()) {
   return `${stamp}-${randomUUID().slice(0, 8)}`;
 }
 
+function envFlag(name, defaultValue = false) {
+  const raw = String(process.env[name] || "").trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(raw)) return true;
+  if (["0", "false", "no", "off"].includes(raw)) return false;
+  return defaultValue;
+}
+
+export function riddleProofScratchRoot() {
+  const configured = (process.env.RIDDLE_PROOF_SCRATCH_ROOT || "").trim();
+  if (configured) return path.resolve(configured);
+  if (envFlag("RIDDLE_PROOF_USE_TMP_SCRATCH", false)) {
+    return path.join("/tmp", "riddle-proof");
+  }
+  return DEFAULT_RIDDLE_PROOF_SCRATCH_ROOT;
+}
+
+export function defaultRiddleProofWorktreeRoot() {
+  return path.join(riddleProofScratchRoot(), ".riddle-proof-worktrees");
+}
+
 export function workspaceRoots({ workspaceRoot = "", currentRepoDir = "" } = {}) {
   const roots = [];
   for (const candidate of [
@@ -332,7 +354,7 @@ function dependencyCacheRoot(projectDir) {
   if (worktreeIndex >= 0) {
     return path.join(resolved.slice(0, worktreeIndex), ".riddle-proof-deps-cache");
   }
-  return path.join(path.dirname(resolved), ".riddle-proof-deps-cache");
+  return path.join(riddleProofScratchRoot(), ".riddle-proof-deps-cache");
 }
 
 function dependencyCacheKey(fingerprint, installCmd) {
@@ -497,6 +519,15 @@ async function main() {
     case "dependency-fingerprint":
       ok({ fingerprint: computeDependencyFingerprint(payload.projectDir) });
       return;
+    case "scratch-root":
+      ok({
+        scratchRoot: riddleProofScratchRoot(),
+        worktreeRoot: defaultRiddleProofWorktreeRoot(),
+      });
+      return;
+    case "dependency-cache-root":
+      ok({ cacheRoot: dependencyCacheRoot(payload.projectDir || process.cwd()) });
+      return;
     default:
       throw new Error(`Unsupported command: ${command}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riddledc/riddle-proof",
-  "version": "0.5.36",
+  "version": "0.5.38",
   "description": "Reusable Riddle Proof contracts and helpers for evidence-backed agent changes.",
   "license": "MIT",
   "author": "RiddleDC",
@@ -54,6 +54,11 @@
       "import": "./dist/proof-session.js",
       "require": "./dist/proof-session.cjs"
     },
+    "./playability": {
+      "types": "./dist/playability.d.ts",
+      "import": "./dist/playability.js",
+      "require": "./dist/playability.cjs"
+    },
     "./openclaw": {
       "types": "./dist/openclaw.d.ts",
       "import": "./dist/openclaw.js",
@@ -87,7 +92,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/proof-session.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/playability.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/author.py

@@ -105,7 +105,7 @@ def authored_proof_plan(state, reference, target_path, baselines, wait_for_selec
     if wait_for_selector:
         lines.append('Stabilize capture on selector: ' + wait_for_selector)
     lines.append('After evidence should load the recon-confirmed route and collect the evidence type required by verification_mode without rediscovering baseline context.')
-    lines.append('For visual modes this usually means a stable screenshot; for data, audio, log, metric, or custom modes it may mean structured proofEvidence, JSON artifacts, console observations, or assertions.')
+    lines.append('For visual modes this usually means a stable screenshot; for playable/gameplay modes it must also prove accepted input, state/time progression, and playfield/canvas pixel motion; for data, audio, log, metric, or custom modes it may mean structured proofEvidence, JSON artifacts, console observations, or assertions.')
     lines.append('Revise this draft only when the supervising agent concludes the proof needs richer interactions, better sense data, or tighter framing.')
     return '\n'.join(lines)
 
@@ -151,6 +151,7 @@ def author_request_payload(state, reference, baselines, current_plan, hypothesis
             'Return the authored packet via author_packet_json when possible. You may also set proof_plan, capture_script, server_path, and wait_for_selector directly.',
             'Keep capture_script concise Playwright statements.',
             'For visual/UI proof, include saveScreenshot(\'after-proof\') exactly once.',
+            'For playable/gameplay proof, start the experience, send keyboard or pointer input, sample state before/after, measure non-HUD playfield/canvas pixel deltas across time, and set window.__riddleProofEvidence.playability or playability_evidence with version riddle-proof.playability.v1.',
             'For data/audio/log/metric/custom proof, screenshots are optional; set window.__riddleProofEvidence inside page.evaluate to a JSON-serializable object with the measured observations the verifier should judge.',
             'Do not assign globalThis.__riddleProofEvidence, window.__riddleProofEvidence, or self.__riddleProofEvidence outside page.evaluate; the Riddle worker context may not expose those globals safely.',
             'Do not begin capture_script with page.goto unless an in-app navigation is genuinely required after the preview opens the target route.',