@riddledc/riddle-proof-packs 0.4.3 → 0.4.5

package/dist/reviewPacketCli.cjs

@@ -0,0 +1,319 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/reviewPacketCli.ts
+var reviewPacketCli_exports = {};
+__export(reviewPacketCli_exports, {
+  main: () => main,
+  parseReviewPacketCliArgs: () => parseReviewPacketCliArgs,
+  writeReviewPacketFiles: () => writeReviewPacketFiles
+});
+module.exports = __toCommonJS(reviewPacketCli_exports);
+var import_node_fs = require("fs");
+var import_node_path = __toESM(require("path"), 1);
+
+// src/humanReviewPacket.ts
+var isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+var asRecord = (value) => isRecord(value) ? value : null;
+var asArray = (value) => Array.isArray(value) ? value : [];
+var getPath = (value, path2) => {
+  let cursor = value;
+  for (const part of path2.split(".")) {
+    if (!isRecord(cursor)) return void 0;
+    cursor = cursor[part];
+  }
+  return cursor;
+};
+var formatValue = (value) => {
+  if (value === null || value === void 0 || value === "") return "not captured";
+  if (typeof value === "number") return Number.isInteger(value) ? String(value) : String(Number(value.toFixed(4)));
+  if (typeof value === "boolean") return value ? "true" : "false";
+  return String(value);
+};
+var formatCodeValue = (value) => `\`${formatValue(value)}\``;
+var formatAction = (action) => {
+  const record = asRecord(action);
+  if (!record) return "not captured";
+  const type = record.type ?? "set_mixer_level";
+  const track = record.track ?? "track";
+  const from = formatValue(record.from);
+  const to = formatValue(record.to);
+  const delta = record.delta === null || record.delta === void 0 ? "" : ` (${formatValue(record.delta)})`;
+  return `${type} ${track}: ${from} -> ${to}${delta}`;
+};
+var addOptionalList = (lines, heading, values) => {
+  const entries = asArray(values).filter((entry) => entry !== null && entry !== void 0 && entry !== "");
+  if (!entries.length) return;
+  lines.push("", `## ${heading}`, "");
+  for (const entry of entries) lines.push(`- ${formatValue(entry)}`);
+};
+function findHumanReviewPacket(value) {
+  if (!value || typeof value !== "object") return null;
+  if (isRecord(value) && value.kind === "human_review_packet") return value;
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      const packet = findHumanReviewPacket(entry);
+      if (packet) return packet;
+    }
+    return null;
+  }
+  for (const entry of Object.values(value)) {
+    const packet = findHumanReviewPacket(entry);
+    if (packet) return packet;
+  }
+  return null;
+}
+function requireHumanReviewPacket(value) {
+  const packet = findHumanReviewPacket(value);
+  if (!packet) throw new Error("No human_review_packet found");
+  return packet;
+}
+function formatHumanReviewPacketMarkdown(packet, options = {}) {
+  if (packet.kind !== "human_review_packet") {
+    throw new Error("Expected a human_review_packet");
+  }
+  const recommendation = asRecord(packet.recommendation) ?? {};
+  const candidate = asRecord(recommendation.candidate) ?? {};
+  const guardrails = asRecord(packet.guardrails) ?? {};
+  const ranking = asRecord(packet.ranking) ?? {};
+  const request = asRecord(packet.request) ?? {};
+  const supportedCandidates = asArray(packet.supportedCandidates);
+  const rejectedCandidates = asArray(packet.rejectedCandidates);
+  const selectedSong = getPath(packet, "target.selectedSong.selectedSong") ?? getPath(packet, "target.routeState.selectedSong");
+  const lines = [
+    `# ${options.title ?? "Human Review Packet"}`,
+    "",
+    `- status: ${formatCodeValue(packet.status)}`,
+    `- domain: ${formatCodeValue(packet.domain)}`,
+    `- evidence_role_pattern: ${formatCodeValue(packet.evidenceRolePattern)}`,
+    `- requested_intent: ${formatValue(packet.requestedIntent)}`,
+    `- selected_song: ${formatValue(selectedSong)}`,
+    "",
+    "## Recommendation",
+    "",
+    `- action: ${formatCodeValue(recommendation.action)}`,
+    `- candidate: ${formatCodeValue(candidate.label)}`,
+    `- candidate_action: ${formatCodeValue(formatAction(candidate.action))}`,
+    `- reason: ${formatValue(recommendation.reason)}`,
+    "",
+    "## Objective Receipts",
+    "",
+    `- supported_candidates: ${formatCodeValue(guardrails.supportedClaimCandidateCount ?? supportedCandidates.length)}`,
+    `- rejected_candidates: ${formatCodeValue(guardrails.rejectedCandidateCount ?? rejectedCandidates.length)}`,
+    `- state_restored_after_loop: ${formatCodeValue(guardrails.stateRestoredAfterLoop)}`,
+    `- candidate_actions_are_transient: ${formatCodeValue(request.candidateActionsAreTransient)}`,
+    `- no_permanent_edit_unless_apply_best: ${formatCodeValue(guardrails.noPermanentEditUnlessApplyBest)}`,
+    "",
+    "## Ranking",
+    "",
+    `- metric: ${formatCodeValue(ranking.metric)}`,
+    `- role: ${formatCodeValue(ranking.role)}`,
+    `- lower_is_better: ${formatCodeValue(ranking.lowerIsBetter)}`,
+    `- baseline: ${formatCodeValue(ranking.baselineCandidateRankingMetric)}`,
+    `- best: ${formatCodeValue(ranking.bestCandidateRankingMetric)}`,
+    `- delta: ${formatCodeValue(ranking.rankingMetricDelta)}`,
+    "",
+    "## Boundary",
+    "",
+    formatValue(packet.proofBoundary)
+  ];
+  addOptionalList(lines, "Listening Prompts", packet.listenerPrompts);
+  addOptionalList(lines, "Caveats", packet.caveats);
+  if (rejectedCandidates.length) {
+    lines.push("", "## Rejected Candidates", "");
+    for (const entry of rejectedCandidates) {
+      const rejected = asRecord(entry) ?? {};
+      const failedReceipts = asArray(rejected.failedReceipts).map(formatValue).join(", ") || "not captured";
+      lines.push(`- ${formatCodeValue(rejected.label)}: ${failedReceipts}`);
+    }
+  }
+  return `${lines.join("\n")}
+`;
+}
+function createHumanReviewPacketArtifacts(proofOrPacket, options = {}) {
+  const packet = requireHumanReviewPacket(proofOrPacket);
+  const markdown = formatHumanReviewPacketMarkdown(packet, options);
+  return {
+    packet,
+    json: `${JSON.stringify(packet, null, 2)}
+`,
+    markdown
+  };
+}
+
+// src/reviewPacketCli.ts
+var DEFAULT_JSON_NAME = "human-review-packet.json";
+var DEFAULT_MARKDOWN_NAME = "human-review-packet.md";
+var USAGE = `riddle-proof-review-packet --proof <path|-> [options]
+
+Extract a human_review_packet from a Riddle Proof artifact and write a compact
+JSON/Markdown handoff for listening or follow-up review.
+
+Options:
+  --proof <path|->       Riddle Proof proof.json/profile-result.json, or '-' for stdin.
+  --output <dir>         Output directory. Defaults to the proof file directory.
+  --json <path>          JSON output path. Defaults to <output>/human-review-packet.json.
+  --markdown <path>      Markdown output path. Defaults to <output>/human-review-packet.md.
+  --title <title>        Markdown title. Defaults to "Human Review Packet".
+  --stdout              Also print the Markdown handoff to stdout.
+  --help                Show this help.
+`;
+var readValue = (argv, index, name) => {
+  const value = argv[index + 1];
+  if (!value || value.startsWith("--")) throw new Error(`${name} requires a value.`);
+  return value;
+};
+function parseReviewPacketCliArgs(argv) {
+  const parsed = {
+    help: false,
+    proofPath: null,
+    outputDir: null,
+    jsonPath: null,
+    markdownPath: null,
+    title: null,
+    stdout: false
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--help" || arg === "-h") {
+      parsed.help = true;
+      continue;
+    }
+    if (arg === "--proof") {
+      parsed.proofPath = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg === "--output" || arg === "--output-dir") {
+      parsed.outputDir = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg === "--json") {
+      parsed.jsonPath = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg === "--markdown" || arg === "--md") {
+      parsed.markdownPath = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg === "--title") {
+      parsed.title = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg === "--stdout") {
+      parsed.stdout = true;
+      continue;
+    }
+    if (!arg.startsWith("--") && !parsed.proofPath) {
+      parsed.proofPath = arg;
+      continue;
+    }
+    throw new Error(`Unknown argument ${arg}.`);
+  }
+  return parsed;
+}
+var readProofArtifact = (proofPath) => {
+  if (proofPath === "-") return JSON.parse((0, import_node_fs.readFileSync)(0, "utf8"));
+  const absoluteProofPath = import_node_path.default.resolve(proofPath);
+  if (!(0, import_node_fs.existsSync)(absoluteProofPath)) {
+    throw new Error(`Proof artifact not found: ${absoluteProofPath}`);
+  }
+  return JSON.parse((0, import_node_fs.readFileSync)(absoluteProofPath, "utf8"));
+};
+var outputDirFor = (proofPath, outputDir) => {
+  if (outputDir) return import_node_path.default.resolve(outputDir);
+  if (proofPath === "-") return process.cwd();
+  return import_node_path.default.dirname(import_node_path.default.resolve(proofPath));
+};
+function writeReviewPacketFiles({
+  proofPath,
+  outputDir,
+  jsonPath,
+  markdownPath,
+  title
+}) {
+  const proof = readProofArtifact(proofPath);
+  const artifacts = createHumanReviewPacketArtifacts(proof, {
+    title: title ?? void 0
+  });
+  const resolvedOutputDir = outputDirFor(proofPath, outputDir);
+  const resolvedJsonPath = import_node_path.default.resolve(jsonPath ?? import_node_path.default.join(resolvedOutputDir, DEFAULT_JSON_NAME));
+  const resolvedMarkdownPath = import_node_path.default.resolve(markdownPath ?? import_node_path.default.join(resolvedOutputDir, DEFAULT_MARKDOWN_NAME));
+  (0, import_node_fs.mkdirSync)(import_node_path.default.dirname(resolvedJsonPath), { recursive: true });
+  (0, import_node_fs.mkdirSync)(import_node_path.default.dirname(resolvedMarkdownPath), { recursive: true });
+  (0, import_node_fs.writeFileSync)(resolvedJsonPath, artifacts.json);
+  (0, import_node_fs.writeFileSync)(resolvedMarkdownPath, artifacts.markdown);
+  return {
+    ...artifacts,
+    jsonPath: resolvedJsonPath,
+    markdownPath: resolvedMarkdownPath
+  };
+}
+async function main(argv = process.argv.slice(2)) {
+  const args = parseReviewPacketCliArgs(argv);
+  if (args.help) {
+    (0, import_node_fs.writeFileSync)(1, USAGE);
+    return;
+  }
+  if (!args.proofPath) throw new Error("--proof is required.");
+  const result = writeReviewPacketFiles({
+    proofPath: args.proofPath,
+    outputDir: args.outputDir,
+    jsonPath: args.jsonPath,
+    markdownPath: args.markdownPath,
+    title: args.title
+  });
+  if (args.stdout) {
+    (0, import_node_fs.writeFileSync)(1, result.markdown);
+  } else {
+    (0, import_node_fs.writeFileSync)(1, `${JSON.stringify({
+      ok: true,
+      json: result.jsonPath,
+      markdown: result.markdownPath,
+      status: result.packet.status ?? null,
+      recommendation: result.packet.recommendation && typeof result.packet.recommendation === "object" ? result.packet.recommendation.candidate?.label ?? null : null
+    }, null, 2)}
+`);
+  }
+}
+main().catch((error) => {
+  (0, import_node_fs.writeFileSync)(2, `${error instanceof Error ? error.message : String(error)}
+`);
+  process.exitCode = 1;
+});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  main,
+  parseReviewPacketCliArgs,
+  writeReviewPacketFiles
+});

package/dist/reviewPacketCli.d.cts

@@ -0,0 +1,28 @@
+import { H as HumanReviewPacket } from './humanReviewPacket-APSxuvat.cjs';
+
+interface ParsedArgs {
+    help: boolean;
+    proofPath: string | null;
+    outputDir: string | null;
+    jsonPath: string | null;
+    markdownPath: string | null;
+    title: string | null;
+    stdout: boolean;
+}
+declare function parseReviewPacketCliArgs(argv: string[]): ParsedArgs;
+declare function writeReviewPacketFiles({ proofPath, outputDir, jsonPath, markdownPath, title, }: {
+    proofPath: string;
+    outputDir: string | null;
+    jsonPath: string | null;
+    markdownPath: string | null;
+    title: string | null;
+}): {
+    jsonPath: string;
+    markdownPath: string;
+    packet: HumanReviewPacket;
+    json: string;
+    markdown: string;
+};
+declare function main(argv?: string[]): Promise<void>;
+
+export { main, parseReviewPacketCliArgs, writeReviewPacketFiles };

package/dist/reviewPacketCli.d.ts

@@ -0,0 +1,28 @@
+import { H as HumanReviewPacket } from './humanReviewPacket-APSxuvat.js';
+
+interface ParsedArgs {
+    help: boolean;
+    proofPath: string | null;
+    outputDir: string | null;
+    jsonPath: string | null;
+    markdownPath: string | null;
+    title: string | null;
+    stdout: boolean;
+}
+declare function parseReviewPacketCliArgs(argv: string[]): ParsedArgs;
+declare function writeReviewPacketFiles({ proofPath, outputDir, jsonPath, markdownPath, title, }: {
+    proofPath: string;
+    outputDir: string | null;
+    jsonPath: string | null;
+    markdownPath: string | null;
+    title: string | null;
+}): {
+    jsonPath: string;
+    markdownPath: string;
+    packet: HumanReviewPacket;
+    json: string;
+    markdown: string;
+};
+declare function main(argv?: string[]): Promise<void>;
+
+export { main, parseReviewPacketCliArgs, writeReviewPacketFiles };

package/dist/reviewPacketCli.js

@@ -0,0 +1,155 @@
+import {
+  createHumanReviewPacketArtifacts
+} from "./chunk-XQ2N4EYF.js";
+
+// src/reviewPacketCli.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import path from "path";
+var DEFAULT_JSON_NAME = "human-review-packet.json";
+var DEFAULT_MARKDOWN_NAME = "human-review-packet.md";
+var USAGE = `riddle-proof-review-packet --proof <path|-> [options]
+
+Extract a human_review_packet from a Riddle Proof artifact and write a compact
+JSON/Markdown handoff for listening or follow-up review.
+
+Options:
+  --proof <path|->       Riddle Proof proof.json/profile-result.json, or '-' for stdin.
+  --output <dir>         Output directory. Defaults to the proof file directory.
+  --json <path>          JSON output path. Defaults to <output>/human-review-packet.json.
+  --markdown <path>      Markdown output path. Defaults to <output>/human-review-packet.md.
+  --title <title>        Markdown title. Defaults to "Human Review Packet".
+  --stdout              Also print the Markdown handoff to stdout.
+  --help                Show this help.
+`;
+var readValue = (argv, index, name) => {
+  const value = argv[index + 1];
+  if (!value || value.startsWith("--")) throw new Error(`${name} requires a value.`);
+  return value;
+};
+function parseReviewPacketCliArgs(argv) {
+  const parsed = {
+    help: false,
+    proofPath: null,
+    outputDir: null,
+    jsonPath: null,
+    markdownPath: null,
+    title: null,
+    stdout: false
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--help" || arg === "-h") {
+      parsed.help = true;
+      continue;
+    }
+    if (arg === "--proof") {
+      parsed.proofPath = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg === "--output" || arg === "--output-dir") {
+      parsed.outputDir = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg === "--json") {
+      parsed.jsonPath = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg === "--markdown" || arg === "--md") {
+      parsed.markdownPath = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg === "--title") {
+      parsed.title = readValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    if (arg === "--stdout") {
+      parsed.stdout = true;
+      continue;
+    }
+    if (!arg.startsWith("--") && !parsed.proofPath) {
+      parsed.proofPath = arg;
+      continue;
+    }
+    throw new Error(`Unknown argument ${arg}.`);
+  }
+  return parsed;
+}
+var readProofArtifact = (proofPath) => {
+  if (proofPath === "-") return JSON.parse(readFileSync(0, "utf8"));
+  const absoluteProofPath = path.resolve(proofPath);
+  if (!existsSync(absoluteProofPath)) {
+    throw new Error(`Proof artifact not found: ${absoluteProofPath}`);
+  }
+  return JSON.parse(readFileSync(absoluteProofPath, "utf8"));
+};
+var outputDirFor = (proofPath, outputDir) => {
+  if (outputDir) return path.resolve(outputDir);
+  if (proofPath === "-") return process.cwd();
+  return path.dirname(path.resolve(proofPath));
+};
+function writeReviewPacketFiles({
+  proofPath,
+  outputDir,
+  jsonPath,
+  markdownPath,
+  title
+}) {
+  const proof = readProofArtifact(proofPath);
+  const artifacts = createHumanReviewPacketArtifacts(proof, {
+    title: title ?? void 0
+  });
+  const resolvedOutputDir = outputDirFor(proofPath, outputDir);
+  const resolvedJsonPath = path.resolve(jsonPath ?? path.join(resolvedOutputDir, DEFAULT_JSON_NAME));
+  const resolvedMarkdownPath = path.resolve(markdownPath ?? path.join(resolvedOutputDir, DEFAULT_MARKDOWN_NAME));
+  mkdirSync(path.dirname(resolvedJsonPath), { recursive: true });
+  mkdirSync(path.dirname(resolvedMarkdownPath), { recursive: true });
+  writeFileSync(resolvedJsonPath, artifacts.json);
+  writeFileSync(resolvedMarkdownPath, artifacts.markdown);
+  return {
+    ...artifacts,
+    jsonPath: resolvedJsonPath,
+    markdownPath: resolvedMarkdownPath
+  };
+}
+async function main(argv = process.argv.slice(2)) {
+  const args = parseReviewPacketCliArgs(argv);
+  if (args.help) {
+    writeFileSync(1, USAGE);
+    return;
+  }
+  if (!args.proofPath) throw new Error("--proof is required.");
+  const result = writeReviewPacketFiles({
+    proofPath: args.proofPath,
+    outputDir: args.outputDir,
+    jsonPath: args.jsonPath,
+    markdownPath: args.markdownPath,
+    title: args.title
+  });
+  if (args.stdout) {
+    writeFileSync(1, result.markdown);
+  } else {
+    writeFileSync(1, `${JSON.stringify({
+      ok: true,
+      json: result.jsonPath,
+      markdown: result.markdownPath,
+      status: result.packet.status ?? null,
+      recommendation: result.packet.recommendation && typeof result.packet.recommendation === "object" ? result.packet.recommendation.candidate?.label ?? null : null
+    }, null, 2)}
+`);
+  }
+}
+main().catch((error) => {
+  writeFileSync(2, `${error instanceof Error ? error.message : String(error)}
+`);
+  process.exitCode = 1;
+});
+export {
+  main,
+  parseReviewPacketCliArgs,
+  writeReviewPacketFiles
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riddledc/riddle-proof-packs",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Reusable proof pack profiles and metadata helpers for the Riddle proof framework.",
   "license": "MIT",
   "author": "RiddleDC",
@@ -23,9 +23,13 @@
   "files": [
     "dist",
     "packs",
+    "bin",
     "LICENSE",
     "README.md"
   ],
+  "bin": {
+    "riddle-proof-review-packet": "./bin/riddle-proof-review-packet"
+  },
   "sideEffects": false,
   "engines": {
     "node": ">=18"
@@ -39,7 +43,7 @@
     "typescript": "^5.4.5"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts --out-dir dist --clean",
+    "build": "tsup src/index.ts src/reviewPacketCli.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"

package/packs/neon-step-sequencer/examples/README.md

@@ -2,7 +2,7 @@
 
 These examples are local Playwright runner outputs captured against LilArcade Neon Step Sequencer on May 24, 2026. They are included to show how this pack records atomic proof claims with explicit evidence-role patterns.
 
-The raw `profile-result.json` files are real runner outputs. They intentionally keep enough evidence to audit the verdict, but the summaries are the preferred place to start.
+The raw `profile-result.json` files are real runner outputs. They intentionally keep enough evidence to audit the verdict, but the summaries are the preferred place to start. Run 006 also includes standalone `human-review-packet.json` and `human-review-packet.md` files generated from the proof artifact.
 
 ## Runs