@riddledc/riddle-proof-packs 0.4.3 → 0.4.5

package/README.md

@@ -24,6 +24,14 @@ Reusable starter profile definitions and proof-pack metadata for Riddle Proof.
   - Returns first manifest entry for a matching `pack_id`.
 - `instantiateRiddleProofProfile(name, options)`:
   - Returns a copy of a profile with optional `url`, `route`, and `target` overrides.
+- `findHumanReviewPacket(proofOrPacket)`:
+  - Recursively finds the first `human_review_packet` in a proof artifact or returns `null`.
+- `requireHumanReviewPacket(proofOrPacket)`:
+  - Same extraction behavior, but throws if no packet is present.
+- `formatHumanReviewPacketMarkdown(packet, options)`:
+  - Formats a compact Markdown handoff with recommendation, objective receipts, ranking role, proof boundary, listening prompts, and caveats.
+- `createHumanReviewPacketArtifacts(proofOrPacket, options)`:
+  - Returns `{ packet, json, markdown }` for storing a standalone review packet next to a proof run.
 
 ## Proof claims and evidence roles
 
@@ -98,6 +106,43 @@ The `audio-mix` directory contains reusable audio-proof authoring guidance, a pr
 
 The `neon-step-sequencer` directory contains the first app-specific ratchet lab under the new architecture. Its profiles declare `current_target` or `interaction_snapshots` evidence-role patterns and explicitly state what they do not prove. The ratchet-loop profile now expects a compact `humanReviewPacket` for listening handoff: supported/rejected candidates, objective guardrails, state restoration, review-order ranking, and taste caveats. The case-study files record the claim, evidence, failure classification, smallest layer changed, and next sharper question for each run.
 
+### Human-review packet handoff
+
+Human-review packets are proof artifacts for subjective follow-up. They are deliberately not taste scores. A packet should say what objective receipts passed, what was preserved, which candidate is ready for listening review, and which caveats remain.
+
+From the CLI:
+
+```sh
+riddle-proof-review-packet \
+  --proof artifacts/riddle-proof/proof.json \
+  --output artifacts/riddle-proof
+```
+
+This writes `human-review-packet.json` and `human-review-packet.md` next to the proof run. Use `--stdout` when an agent should read the Markdown handoff immediately.
+
+```ts
+import {
+  createHumanReviewPacketArtifacts,
+  findHumanReviewPacket,
+  formatHumanReviewPacketMarkdown,
+} from "@riddledc/riddle-proof-packs";
+
+const proof = JSON.parse(await fs.promises.readFile("proof.json", "utf8"));
+const packet = findHumanReviewPacket(proof);
+if (!packet) throw new Error("proof did not emit a human review packet");
+
+const markdown = formatHumanReviewPacketMarkdown(packet, {
+  title: "Neon Human Review Packet",
+});
+const artifacts = createHumanReviewPacketArtifacts(proof, {
+  title: "Neon Human Review Packet",
+});
+
+console.log(markdown);
+await fs.promises.writeFile("human-review-packet.json", artifacts.json);
+await fs.promises.writeFile("human-review-packet.md", artifacts.markdown);
+```
+
 ## Usage
 
 ```ts

package/bin/riddle-proof-review-packet

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+const cliPath = new URL("../dist/reviewPacketCli.js", import.meta.url);
+await import(cliPath.href);

package/dist/chunk-XQ2N4EYF.js

@@ -0,0 +1,135 @@
+// 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, path) => {
+  let cursor = value;
+  for (const part of path.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
+  };
+}
+
+export {
+  findHumanReviewPacket,
+  requireHumanReviewPacket,
+  formatHumanReviewPacketMarkdown,
+  createHumanReviewPacketArtifacts
+};

package/dist/humanReviewPacket-APSxuvat.d.cts

@@ -0,0 +1,17 @@
+type HumanReviewPacket = Record<string, unknown> & {
+    kind: "human_review_packet";
+};
+interface HumanReviewPacketMarkdownOptions {
+    title?: string;
+}
+interface HumanReviewPacketArtifacts {
+    packet: HumanReviewPacket;
+    json: string;
+    markdown: string;
+}
+declare function findHumanReviewPacket(value: unknown): HumanReviewPacket | null;
+declare function requireHumanReviewPacket(value: unknown): HumanReviewPacket;
+declare function formatHumanReviewPacketMarkdown(packet: HumanReviewPacket, options?: HumanReviewPacketMarkdownOptions): string;
+declare function createHumanReviewPacketArtifacts(proofOrPacket: unknown, options?: HumanReviewPacketMarkdownOptions): HumanReviewPacketArtifacts;
+
+export { type HumanReviewPacket as H, type HumanReviewPacketArtifacts as a, type HumanReviewPacketMarkdownOptions as b, createHumanReviewPacketArtifacts as c, formatHumanReviewPacketMarkdown as d, findHumanReviewPacket as f, requireHumanReviewPacket as r };

package/dist/humanReviewPacket-APSxuvat.d.ts

@@ -0,0 +1,17 @@
+type HumanReviewPacket = Record<string, unknown> & {
+    kind: "human_review_packet";
+};
+interface HumanReviewPacketMarkdownOptions {
+    title?: string;
+}
+interface HumanReviewPacketArtifacts {
+    packet: HumanReviewPacket;
+    json: string;
+    markdown: string;
+}
+declare function findHumanReviewPacket(value: unknown): HumanReviewPacket | null;
+declare function requireHumanReviewPacket(value: unknown): HumanReviewPacket;
+declare function formatHumanReviewPacketMarkdown(packet: HumanReviewPacket, options?: HumanReviewPacketMarkdownOptions): string;
+declare function createHumanReviewPacketArtifacts(proofOrPacket: unknown, options?: HumanReviewPacketMarkdownOptions): HumanReviewPacketArtifacts;
+
+export { type HumanReviewPacket as H, type HumanReviewPacketArtifacts as a, type HumanReviewPacketMarkdownOptions as b, createHumanReviewPacketArtifacts as c, formatHumanReviewPacketMarkdown as d, findHumanReviewPacket as f, requireHumanReviewPacket as r };

package/dist/index.cjs

@@ -22,6 +22,9 @@ var index_exports = {};
 __export(index_exports, {
   RIDDLE_PROOF_PACK_MANIFEST: () => RIDDLE_PROOF_PACK_MANIFEST,
   RIDDLE_PROOF_PACK_PROFILES: () => RIDDLE_PROOF_PACK_PROFILES,
+  createHumanReviewPacketArtifacts: () => createHumanReviewPacketArtifacts,
+  findHumanReviewPacket: () => findHumanReviewPacket,
+  formatHumanReviewPacketMarkdown: () => formatHumanReviewPacketMarkdown,
   getPackEnabledRiddleProofPackProfiles: () => getPackEnabledRiddleProofPackProfiles,
   getRiddleProofPackProfile: () => getRiddleProofPackProfile,
   getRiddleProofPackProfileByPackId: () => getRiddleProofPackProfileByPackId,
@@ -29,7 +32,8 @@ __export(index_exports, {
   getRiddleProofProfilesByPackId: () => getRiddleProofProfilesByPackId,
   instantiateRiddleProofProfile: () => instantiateRiddleProofProfile,
   listRiddleProofPackProfiles: () => listRiddleProofPackProfiles,
-  listRiddleProofPacks: () => listRiddleProofPacks
+  listRiddleProofPacks: () => listRiddleProofPacks,
+  requireHumanReviewPacket: () => requireHumanReviewPacket
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -2345,10 +2349,142 @@ function instantiateRiddleProofProfile(profileName, options = {}) {
     }
   );
 }
+
+// src/humanReviewPacket.ts
+var isRecord2 = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+var asRecord = (value) => isRecord2(value) ? value : null;
+var asArray = (value) => Array.isArray(value) ? value : [];
+var getPath = (value, path) => {
+  let cursor = value;
+  for (const part of path.split(".")) {
+    if (!isRecord2(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 (isRecord2(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
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   RIDDLE_PROOF_PACK_MANIFEST,
   RIDDLE_PROOF_PACK_PROFILES,
+  createHumanReviewPacketArtifacts,
+  findHumanReviewPacket,
+  formatHumanReviewPacketMarkdown,
   getPackEnabledRiddleProofPackProfiles,
   getRiddleProofPackProfile,
   getRiddleProofPackProfileByPackId,
@@ -2356,5 +2492,6 @@ function instantiateRiddleProofProfile(profileName, options = {}) {
   getRiddleProofProfilesByPackId,
   instantiateRiddleProofProfile,
   listRiddleProofPackProfiles,
-  listRiddleProofPacks
+  listRiddleProofPacks,
+  requireHumanReviewPacket
 });

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import * as _riddledc_riddle_proof from '@riddledc/riddle-proof';
 import { RiddleProofProfile } from '@riddledc/riddle-proof';
+export { H as HumanReviewPacket, a as HumanReviewPacketArtifacts, b as HumanReviewPacketMarkdownOptions, c as createHumanReviewPacketArtifacts, f as findHumanReviewPacket, d as formatHumanReviewPacketMarkdown, r as requireHumanReviewPacket } from './humanReviewPacket-APSxuvat.cjs';
 
 interface RiddleProofPackProfileManifest {
     /** Profile slug and canonical manifest key. */

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as _riddledc_riddle_proof from '@riddledc/riddle-proof';
 import { RiddleProofProfile } from '@riddledc/riddle-proof';
+export { H as HumanReviewPacket, a as HumanReviewPacketArtifacts, b as HumanReviewPacketMarkdownOptions, c as createHumanReviewPacketArtifacts, f as findHumanReviewPacket, d as formatHumanReviewPacketMarkdown, r as requireHumanReviewPacket } from './humanReviewPacket-APSxuvat.js';
 
 interface RiddleProofPackProfileManifest {
     /** Profile slug and canonical manifest key. */

package/dist/index.js

@@ -1,3 +1,10 @@
+import {
+  createHumanReviewPacketArtifacts,
+  findHumanReviewPacket,
+  formatHumanReviewPacketMarkdown,
+  requireHumanReviewPacket
+} from "./chunk-XQ2N4EYF.js";
+
 // src/pack-data.ts
 import { normalizeRiddleProofProfile } from "@riddledc/riddle-proof";
 
@@ -2313,6 +2320,9 @@ function instantiateRiddleProofProfile(profileName, options = {}) {
 export {
   RIDDLE_PROOF_PACK_MANIFEST,
   RIDDLE_PROOF_PACK_PROFILES,
+  createHumanReviewPacketArtifacts,
+  findHumanReviewPacket,
+  formatHumanReviewPacketMarkdown,
   getPackEnabledRiddleProofPackProfiles,
   getRiddleProofPackProfile,
   getRiddleProofPackProfileByPackId,
@@ -2320,5 +2330,6 @@ export {
   getRiddleProofProfilesByPackId,
   instantiateRiddleProofProfile,
   listRiddleProofPackProfiles,
-  listRiddleProofPacks
+  listRiddleProofPacks,
+  requireHumanReviewPacket
 };