@riddledc/riddle-proof-packs 0.4.3 → 0.4.4

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,33 @@ 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.
+
+```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/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

@@ -59,4 +59,20 @@ interface RiddleProofPackProfileOverrides {
  */
 declare function instantiateRiddleProofProfile(profileName: string, options?: RiddleProofPackProfileOverrides): RiddleProofProfile;
 
-export { RIDDLE_PROOF_PACK_MANIFEST, RIDDLE_PROOF_PACK_PROFILES, type RiddleProofPackProfileManifest, getPackEnabledRiddleProofPackProfiles, getRiddleProofPackProfile, getRiddleProofPackProfileByPackId, getRiddleProofPackProfileManifest, getRiddleProofProfilesByPackId, instantiateRiddleProofProfile, listRiddleProofPackProfiles, listRiddleProofPacks };
+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, type HumanReviewPacketArtifacts, type HumanReviewPacketMarkdownOptions, RIDDLE_PROOF_PACK_MANIFEST, RIDDLE_PROOF_PACK_PROFILES, type RiddleProofPackProfileManifest, createHumanReviewPacketArtifacts, findHumanReviewPacket, formatHumanReviewPacketMarkdown, getPackEnabledRiddleProofPackProfiles, getRiddleProofPackProfile, getRiddleProofPackProfileByPackId, getRiddleProofPackProfileManifest, getRiddleProofProfilesByPackId, instantiateRiddleProofProfile, listRiddleProofPackProfiles, listRiddleProofPacks, requireHumanReviewPacket };

package/dist/index.d.ts

@@ -59,4 +59,20 @@ interface RiddleProofPackProfileOverrides {
  */
 declare function instantiateRiddleProofProfile(profileName: string, options?: RiddleProofPackProfileOverrides): RiddleProofProfile;
 
-export { RIDDLE_PROOF_PACK_MANIFEST, RIDDLE_PROOF_PACK_PROFILES, type RiddleProofPackProfileManifest, getPackEnabledRiddleProofPackProfiles, getRiddleProofPackProfile, getRiddleProofPackProfileByPackId, getRiddleProofPackProfileManifest, getRiddleProofProfilesByPackId, instantiateRiddleProofProfile, listRiddleProofPackProfiles, listRiddleProofPacks };
+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, type HumanReviewPacketArtifacts, type HumanReviewPacketMarkdownOptions, RIDDLE_PROOF_PACK_MANIFEST, RIDDLE_PROOF_PACK_PROFILES, type RiddleProofPackProfileManifest, createHumanReviewPacketArtifacts, findHumanReviewPacket, formatHumanReviewPacketMarkdown, getPackEnabledRiddleProofPackProfiles, getRiddleProofPackProfile, getRiddleProofPackProfileByPackId, getRiddleProofPackProfileManifest, getRiddleProofProfilesByPackId, instantiateRiddleProofProfile, listRiddleProofPackProfiles, listRiddleProofPacks, requireHumanReviewPacket };

package/dist/index.js

@@ -2310,9 +2310,141 @@ 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
+  };
+}
 export {
   RIDDLE_PROOF_PACK_MANIFEST,
   RIDDLE_PROOF_PACK_PROFILES,
+  createHumanReviewPacketArtifacts,
+  findHumanReviewPacket,
+  formatHumanReviewPacketMarkdown,
   getPackEnabledRiddleProofPackProfiles,
   getRiddleProofPackProfile,
   getRiddleProofPackProfileByPackId,
@@ -2320,5 +2452,6 @@ export {
   getRiddleProofProfilesByPackId,
   instantiateRiddleProofProfile,
   listRiddleProofPackProfiles,
-  listRiddleProofPacks
+  listRiddleProofPacks,
+  requireHumanReviewPacket
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riddledc/riddle-proof-packs",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "Reusable proof pack profiles and metadata helpers for the Riddle proof framework.",
   "license": "MIT",
   "author": "RiddleDC",

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
 

package/packs/neon-step-sequencer/examples/run-006-ratchet-loop-human-review-packet/human-review-packet.json

@@ -0,0 +1,795 @@
+{
+  "version": "neon-step-sequencer.human-review-packet.v1",
+  "kind": "human_review_packet",
+  "domain": "audio_mix",
+  "status": "candidate_ready_for_listening_review",
+  "evidenceRolePattern": "interaction_snapshots",
+  "proofBoundary": "Objective receipts support or reject candidate change claims; musical taste still requires listening review.",
+  "requestedIntent": "turn the chord part down a little",
+  "target": {
+    "routeState": {
+      "proofKind": "neon-route-state",
+      "route": "/games/drum-sequencer",
+      "mode": "song",
+      "selectedSong": "Monkberry Moon Delight (Tab)",
+      "selectedPartIndex": 0
+    },
+    "selectedSong": {
+      "proofKind": "neon-selected-song",
+      "selectedSong": "Monkberry Moon Delight (Tab)",
+      "partCount": 9,
+      "mixProfile": {
+        "id": "monkberry-moon-delight-eq-lane-mix-v7",
+        "label": "Monkberry humanized EQ mix",
+        "description": "Humanized imported-tab mix with softer vocal formants, fuller bass harmonics, darker pads, and a deeper shared room/plate space.",
+        "proofWindows": [
+          {
+            "name": "introBed",
+            "label": "Intro Bed",
+            "bars": 1,
+            "seed": "riddle-sequencer-bed",
+            "requiredActive": [
+              "bass",
+              "chord",
+              "guitar"
+            ]
+          },
+          {
+            "name": "vocalEntry",
+            "label": "Vocal Entry",
+            "bars": 3,
+            "seed": "riddle-sequencer-vocal-melody",
+            "requiredActive": [
+              "rhythmSynth"
+            ]
+          }
+        ],
+        "eqSettings": {
+          "kick": [
+            2.2,
+            -0.8,
+            -3.2,
+            -4.5,
+            -5.5,
+            -5,
+            0.8,
+            0
+          ],
+          "snare": [
+            -6,
+            -2.5,
+            1.4,
+            -3,
+            -0.6,
+            1.4,
+            0.4,
+            -1.8
+          ],
+          "hat": [
+            -12,
+            -12,
+            -12,
+            -10,
+            -7,
+            -2.5,
+            -2.2,
+            -1.1
+          ],
+          "clap": [
+            -12,
+            -8,
+            -4,
+            -1.5,
+            0.8,
+            0,
+            -1,
+            -2
+          ],
+          "rim": [
+            -12,
+            -8,
+            -3.5,
+            -1.2,
+            0,
+            -0.5,
+            -1.2,
+            -2
+          ],
+          "bass": [
+            -1.2,
+            2.8,
+            -1.4,
+            -4.8,
+            -6,
+            -8,
+            -10,
+            -10
+          ],
+          "chord": [
+            -8,
+            -2.8,
+            -4.8,
+            -0.8,
+            -1,
+            -2.8,
+            -4.8,
+            -6.5
+          ],
+          "guitar": [
+            -8,
+            -4.8,
+            -3.4,
+            -2.2,
+            1.2,
+            1.4,
+            0.2,
+            -1.8
+          ],
+          "rhythmSynth": [
+            -10,
+            -6,
+            -3.8,
+            -1.6,
+            0.8,
+            1.8,
+            0,
+            -2.8
+          ]
+        },
+        "mixLanes": {
+          "kick": "Sub thump around 60 Hz with most low-mid box removed.",
+          "bass": "Bass foundation around 80-160 Hz with more 120 Hz body for small speakers.",
+          "snare": "Backbeat body near 250 Hz with controlled upper presence.",
+          "hat": "Soft high pulse, trimmed in brittle 4-8 kHz bands.",
+          "chord": "Darker pad bed with more room depth and less plasticky top.",
+          "guitar": "Mid/presence lane around 1-2 kHz, wider than the pad and glued into the shared music bus.",
+          "rhythmSynth": "Vocal melody lane in the upper mids, forward enough to survive the small-speaker monitor without crowding 1 kHz."
+        }
+      }
+    }
+  },
+  "request": {
+    "strategy": "mix-level-search",
+    "focusTracks": [
+      "bass",
+      "chord",
+      "guitar",
+      "rhythmSynth"
+    ],
+    "maxIterations": 6,
+    "monitorProfile": "smallSpeaker",
+    "restore": true,
+    "applyBest": false,
+    "candidateActionsAreTransient": true
+  },
+  "recommendation": {
+    "action": "review_before_applying_candidate",
+    "candidate": {
+      "index": 6,
+      "label": "chord -0.10",
+      "status": "supported",
+      "classification": null,
+      "claim": "Setting chord level from 0.38 to 0.28 changes rendered chord metrics while preserving Neon proof invariants.",
+      "action": {
+        "type": "set_mixer_level",
+        "track": "chord",
+        "from": 0.38,
+        "to": 0.28,
+        "delta": -0.1
+      },
+      "rankingMetric": 27.0709,
+      "receipts": [
+        {
+          "name": "mixer_edit_accepted",
+          "ok": true
+        },
+        {
+          "name": "contract_mixer_level_reflects_action",
+          "ok": true
+        },
+        {
+          "name": "rendered_target_metric_changed",
+          "ok": true
+        },
+        {
+          "name": "required_instruments_preserved",
+          "ok": true
+        },
+        {
+          "name": "no_clipping",
+          "ok": true
+        },
+        {
+          "name": "no_low_level_proof_window",
+          "ok": true
+        }
+      ],
+      "failedReceipts": [],
+      "guardrails": {
+        "mixerEditAccepted": true,
+        "contractLevelReflected": true,
+        "renderedTargetMoved": true,
+        "requiredInstrumentsPreserved": true,
+        "noClipping": true,
+        "noLowLevelProofWindow": true
+      },
+      "targetMovement": {
+        "track": "chord",
+        "moved": true,
+        "deltas": {
+          "rms": -0.0012,
+          "peak": -0.0088,
+          "totalEnergy": -0.000003
+        },
+        "before": {
+          "track": "chord",
+          "sampleCount": 2,
+          "activeCount": 0,
+          "rms": 0.0062,
+          "peak": 0.0334,
+          "totalEnergy": 0.000007
+        },
+        "after": {
+          "track": "chord",
+          "sampleCount": 2,
+          "activeCount": 0,
+          "rms": 0.005,
+          "peak": 0.0246,
+          "totalEnergy": 0.000004
+        }
+      },
+      "summary": {
+        "status": "passed",
+        "windowCount": 2,
+        "findingCount": 0,
+        "mixProfile": {
+          "id": "monkberry-moon-delight-eq-lane-mix-v7",
+          "label": "Monkberry humanized EQ mix"
+        }
+      }
+    },
+    "reason": "All objective claim receipts passed for this candidate; ranking only orders listening review."
+  },
+  "supportedCandidates": [
+    {
+      "index": 6,
+      "label": "chord -0.10",
+      "status": "supported",
+      "classification": null,
+      "claim": "Setting chord level from 0.38 to 0.28 changes rendered chord metrics while preserving Neon proof invariants.",
+      "action": {
+        "type": "set_mixer_level",
+        "track": "chord",
+        "from": 0.38,
+        "to": 0.28,
+        "delta": -0.1
+      },
+      "rankingMetric": 27.0709,
+      "receipts": [
+        {
+          "name": "mixer_edit_accepted",
+          "ok": true
+        },
+        {
+          "name": "contract_mixer_level_reflects_action",
+          "ok": true
+        },
+        {
+          "name": "rendered_target_metric_changed",
+          "ok": true
+        },
+        {
+          "name": "required_instruments_preserved",
+          "ok": true
+        },
+        {
+          "name": "no_clipping",
+          "ok": true
+        },
+        {
+          "name": "no_low_level_proof_window",
+          "ok": true
+        }
+      ],
+      "failedReceipts": [],
+      "guardrails": {
+        "mixerEditAccepted": true,
+        "contractLevelReflected": true,
+        "renderedTargetMoved": true,
+        "requiredInstrumentsPreserved": true,
+        "noClipping": true,
+        "noLowLevelProofWindow": true
+      },
+      "targetMovement": {
+        "track": "chord",
+        "moved": true,
+        "deltas": {
+          "rms": -0.0012,
+          "peak": -0.0088,
+          "totalEnergy": -0.000003
+        },
+        "before": {
+          "track": "chord",
+          "sampleCount": 2,
+          "activeCount": 0,
+          "rms": 0.0062,
+          "peak": 0.0334,
+          "totalEnergy": 0.000007
+        },
+        "after": {
+          "track": "chord",
+          "sampleCount": 2,
+          "activeCount": 0,
+          "rms": 0.005,
+          "peak": 0.0246,
+          "totalEnergy": 0.000004
+        }
+      },
+      "summary": {
+        "status": "passed",
+        "windowCount": 2,
+        "findingCount": 0,
+        "mixProfile": {
+          "id": "monkberry-moon-delight-eq-lane-mix-v7",
+          "label": "Monkberry humanized EQ mix"
+        }
+      }
+    },
+    {
+      "index": 4,
+      "label": "bass -0.18",
+      "status": "supported",
+      "classification": null,
+      "claim": "Setting bass level from 0.62 to 0.44 changes rendered bass metrics while preserving Neon proof invariants.",
+      "action": {
+        "type": "set_mixer_level",
+        "track": "bass",
+        "from": 0.62,
+        "to": 0.44,
+        "delta": -0.18
+      },
+      "rankingMetric": 27.4894,
+      "receipts": [
+        {
+          "name": "mixer_edit_accepted",
+          "ok": true
+        },
+        {
+          "name": "contract_mixer_level_reflects_action",
+          "ok": true
+        },
+        {
+          "name": "rendered_target_metric_changed",
+          "ok": true
+        },
+        {
+          "name": "required_instruments_preserved",
+          "ok": true
+        },
+        {
+          "name": "no_clipping",
+          "ok": true
+        },
+        {
+          "name": "no_low_level_proof_window",
+          "ok": true
+        }
+      ],
+      "failedReceipts": [],
+      "guardrails": {
+        "mixerEditAccepted": true,
+        "contractLevelReflected": true,
+        "renderedTargetMoved": true,
+        "requiredInstrumentsPreserved": true,
+        "noClipping": true,
+        "noLowLevelProofWindow": true
+      },
+      "targetMovement": {
+        "track": "bass",
+        "moved": true,
+        "deltas": {
+          "rms": -0.01625,
+          "peak": -0.0535,
+          "totalEnergy": -0.000304
+        },
+        "before": {
+          "track": "bass",
+          "sampleCount": 2,
+          "activeCount": 0,
+          "rms": 0.058,
+          "peak": 0.18415,
+          "totalEnergy": 0.000621
+        },
+        "after": {
+          "track": "bass",
+          "sampleCount": 2,
+          "activeCount": 0,
+          "rms": 0.04175,
+          "peak": 0.13065,
+          "totalEnergy": 0.000317
+        }
+      },
+      "summary": {
+        "status": "passed",
+        "windowCount": 2,
+        "findingCount": 0,
+        "mixProfile": {
+          "id": "monkberry-moon-delight-eq-lane-mix-v7",
+          "label": "Monkberry humanized EQ mix"
+        }
+      }
+    },
+    {
+      "index": 5,
+      "label": "chord +0.12",
+      "status": "supported",
+      "classification": null,
+      "claim": "Setting chord level from 0.38 to 0.50 changes rendered chord metrics while preserving Neon proof invariants.",
+      "action": {
+        "type": "set_mixer_level",
+        "track": "chord",
+        "from": 0.38,
+        "to": 0.5,
+        "delta": 0.12
+      },
+      "rankingMetric": 28.5162,
+      "receipts": [
+        {
+          "name": "mixer_edit_accepted",
+          "ok": true
+        },
+        {
+          "name": "contract_mixer_level_reflects_action",
+          "ok": true
+        },
+        {
+          "name": "rendered_target_metric_changed",
+          "ok": true
+        },
+        {
+          "name": "required_instruments_preserved",
+          "ok": true
+        },
+        {
+          "name": "no_clipping",
+          "ok": true
+        },
+        {
+          "name": "no_low_level_proof_window",
+          "ok": true
+        }
+      ],
+      "failedReceipts": [],
+      "guardrails": {
+        "mixerEditAccepted": true,
+        "contractLevelReflected": true,
+        "renderedTargetMoved": true,
+        "requiredInstrumentsPreserved": true,
+        "noClipping": true,
+        "noLowLevelProofWindow": true
+      },
+      "targetMovement": {
+        "track": "chord",
+        "moved": true,
+        "deltas": {
+          "rms": 0.002,
+          "peak": 0.0105,
+          "totalEnergy": 0.000005
+        },
+        "before": {
+          "track": "chord",
+          "sampleCount": 2,
+          "activeCount": 0,
+          "rms": 0.0062,
+          "peak": 0.0334,
+          "totalEnergy": 0.000007
+        },
+        "after": {
+          "track": "chord",
+          "sampleCount": 2,
+          "activeCount": 0,
+          "rms": 0.0082,
+          "peak": 0.0439,
+          "totalEnergy": 0.000012
+        }
+      },
+      "summary": {
+        "status": "passed",
+        "windowCount": 2,
+        "findingCount": 0,
+        "mixProfile": {
+          "id": "monkberry-moon-delight-eq-lane-mix-v7",
+          "label": "Monkberry humanized EQ mix"
+        }
+      }
+    },
+    {
+      "index": 2,
+      "label": "bass -0.10",
+      "status": "supported",
+      "classification": null,
+      "claim": "Setting bass level from 0.62 to 0.52 changes rendered bass metrics while preserving Neon proof invariants.",
+      "action": {
+        "type": "set_mixer_level",
+        "track": "bass",
+        "from": 0.62,
+        "to": 0.52,
+        "delta": -0.1
+      },
+      "rankingMetric": 29.17,
+      "receipts": [
+        {
+          "name": "mixer_edit_accepted",
+          "ok": true
+        },
+        {
+          "name": "contract_mixer_level_reflects_action",
+          "ok": true
+        },
+        {
+          "name": "rendered_target_metric_changed",
+          "ok": true
+        },
+        {
+          "name": "required_instruments_preserved",
+          "ok": true
+        },
+        {
+          "name": "no_clipping",
+          "ok": true
+        },
+        {
+          "name": "no_low_level_proof_window",
+          "ok": true
+        }
+      ],
+      "failedReceipts": [],
+      "guardrails": {
+        "mixerEditAccepted": true,
+        "contractLevelReflected": true,
+        "renderedTargetMoved": true,
+        "requiredInstrumentsPreserved": true,
+        "noClipping": true,
+        "noLowLevelProofWindow": true
+      },
+      "targetMovement": {
+        "track": "bass",
+        "moved": true,
+        "deltas": {
+          "rms": -0.00935,
+          "peak": -0.02975,
+          "totalEnergy": -0.000184
+        },
+        "before": {
+          "track": "bass",
+          "sampleCount": 2,
+          "activeCount": 0,
+          "rms": 0.058,
+          "peak": 0.18415,
+          "totalEnergy": 0.000621
+        },
+        "after": {
+          "track": "bass",
+          "sampleCount": 2,
+          "activeCount": 0,
+          "rms": 0.04865,
+          "peak": 0.1544,
+          "totalEnergy": 0.000437
+        }
+      },
+      "summary": {
+        "status": "passed",
+        "windowCount": 2,
+        "findingCount": 0,
+        "mixProfile": {
+          "id": "monkberry-moon-delight-eq-lane-mix-v7",
+          "label": "Monkberry humanized EQ mix"
+        }
+      }
+    },
+    {
+      "index": 1,
+      "label": "bass +0.12",
+      "status": "supported",
+      "classification": null,
+      "claim": "Setting bass level from 0.62 to 0.74 changes rendered bass metrics while preserving Neon proof invariants.",
+      "action": {
+        "type": "set_mixer_level",
+        "track": "bass",
+        "from": 0.62,
+        "to": 0.74,
+        "delta": 0.12
+      },
+      "rankingMetric": 31.7993,
+      "receipts": [
+        {
+          "name": "mixer_edit_accepted",
+          "ok": true
+        },
+        {
+          "name": "contract_mixer_level_reflects_action",
+          "ok": true
+        },
+        {
+          "name": "rendered_target_metric_changed",
+          "ok": true
+        },
+        {
+          "name": "required_instruments_preserved",
+          "ok": true
+        },
+        {
+          "name": "no_clipping",
+          "ok": true
+        },
+        {
+          "name": "no_low_level_proof_window",
+          "ok": true
+        }
+      ],
+      "failedReceipts": [],
+      "guardrails": {
+        "mixerEditAccepted": true,
+        "contractLevelReflected": true,
+        "renderedTargetMoved": true,
+        "requiredInstrumentsPreserved": true,
+        "noClipping": true,
+        "noLowLevelProofWindow": true
+      },
+      "targetMovement": {
+        "track": "bass",
+        "moved": true,
+        "deltas": {
+          "rms": 0.01125,
+          "peak": 0.0356,
+          "totalEnergy": 0.000264
+        },
+        "before": {
+          "track": "bass",
+          "sampleCount": 2,
+          "activeCount": 0,
+          "rms": 0.058,
+          "peak": 0.18415,
+          "totalEnergy": 0.000621
+        },
+        "after": {
+          "track": "bass",
+          "sampleCount": 2,
+          "activeCount": 0,
+          "rms": 0.06925,
+          "peak": 0.21975,
+          "totalEnergy": 0.000885
+        }
+      },
+      "summary": {
+        "status": "passed",
+        "windowCount": 2,
+        "findingCount": 0,
+        "mixProfile": {
+          "id": "monkberry-moon-delight-eq-lane-mix-v7",
+          "label": "Monkberry humanized EQ mix"
+        }
+      }
+    },
+    {
+      "index": 3,
+      "label": "bass +0.20",
+      "status": "supported",
+      "classification": null,
+      "claim": "Setting bass level from 0.62 to 0.82 changes rendered bass metrics while preserving Neon proof invariants.",
+      "action": {
+        "type": "set_mixer_level",
+        "track": "bass",
+        "from": 0.62,
+        "to": 0.82,
+        "delta": 0.2
+      },
+      "rankingMetric": 35.2559,
+      "receipts": [
+        {
+          "name": "mixer_edit_accepted",
+          "ok": true
+        },
+        {
+          "name": "contract_mixer_level_reflects_action",
+          "ok": true
+        },
+        {
+          "name": "rendered_target_metric_changed",
+          "ok": true
+        },
+        {
+          "name": "required_instruments_preserved",
+          "ok": true
+        },
+        {
+          "name": "no_clipping",
+          "ok": true
+        },
+        {
+          "name": "no_low_level_proof_window",
+          "ok": true
+        }
+      ],
+      "failedReceipts": [],
+      "guardrails": {
+        "mixerEditAccepted": true,
+        "contractLevelReflected": true,
+        "renderedTargetMoved": true,
+        "requiredInstrumentsPreserved": true,
+        "noClipping": true,
+        "noLowLevelProofWindow": true
+      },
+      "targetMovement": {
+        "track": "bass",
+        "moved": true,
+        "deltas": {
+          "rms": 0.0187,
+          "peak": 0.0594,
+          "totalEnergy": 0.000466
+        },
+        "before": {
+          "track": "bass",
+          "sampleCount": 2,
+          "activeCount": 0,
+          "rms": 0.058,
+          "peak": 0.18415,
+          "totalEnergy": 0.000621
+        },
+        "after": {
+          "track": "bass",
+          "sampleCount": 2,
+          "activeCount": 0,
+          "rms": 0.0767,
+          "peak": 0.24355,
+          "totalEnergy": 0.001087
+        }
+      },
+      "summary": {
+        "status": "passed",
+        "windowCount": 2,
+        "findingCount": 0,
+        "mixProfile": {
+          "id": "monkberry-moon-delight-eq-lane-mix-v7",
+          "label": "Monkberry humanized EQ mix"
+        }
+      }
+    }
+  ],
+  "rejectedCandidates": [],
+  "ranking": {
+    "metric": "objective_mix_health_penalty",
+    "role": "review_order_only",
+    "lowerIsBetter": true,
+    "baselineCandidateRankingMetric": 28.8336,
+    "bestCandidateRankingMetric": 27.0709,
+    "rankingMetricDelta": 1.7626
+  },
+  "baseline": {
+    "status": "passed",
+    "windowCount": 2,
+    "findingCount": 0,
+    "mixProfile": {
+      "id": "monkberry-moon-delight-eq-lane-mix-v7",
+      "label": "Monkberry humanized EQ mix"
+    }
+  },
+  "guardrails": {
+    "supportedClaimCandidateCount": 6,
+    "rejectedCandidateCount": 0,
+    "stateRestoredAfterLoop": true,
+    "noPermanentEditUnlessApplyBest": true
+  },
+  "listenerPrompts": [
+    "Does the supported candidate match the requested musical intent?",
+    "Is the changed part better balanced in the proof window?",
+    "Did the proof window contain the musical material being judged?",
+    "Would another section or speaker profile change the listening decision?"
+  ],
+  "caveats": [
+    "This packet does not prove subjective mix quality.",
+    "A supported candidate proves objective receipts and guardrails only.",
+    "Ranking orders review; it is not a taste score.",
+    "Keep or apply the candidate only after listening review."
+  ]
+}

package/packs/neon-step-sequencer/examples/run-006-ratchet-loop-human-review-packet/human-review-packet.md

@@ -0,0 +1,49 @@
+# Neon Human Review Packet
+
+- status: `candidate_ready_for_listening_review`
+- domain: `audio_mix`
+- evidence_role_pattern: `interaction_snapshots`
+- requested_intent: turn the chord part down a little
+- selected_song: Monkberry Moon Delight (Tab)
+
+## Recommendation
+
+- action: `review_before_applying_candidate`
+- candidate: `chord -0.10`
+- candidate_action: `set_mixer_level chord: 0.38 -> 0.28 (-0.1)`
+- reason: All objective claim receipts passed for this candidate; ranking only orders listening review.
+
+## Objective Receipts
+
+- supported_candidates: `6`
+- rejected_candidates: `0`
+- state_restored_after_loop: `true`
+- candidate_actions_are_transient: `true`
+- no_permanent_edit_unless_apply_best: `true`
+
+## Ranking
+
+- metric: `objective_mix_health_penalty`
+- role: `review_order_only`
+- lower_is_better: `true`
+- baseline: `28.8336`
+- best: `27.0709`
+- delta: `1.7626`
+
+## Boundary
+
+Objective receipts support or reject candidate change claims; musical taste still requires listening review.
+
+## Listening Prompts
+
+- Does the supported candidate match the requested musical intent?
+- Is the changed part better balanced in the proof window?
+- Did the proof window contain the musical material being judged?
+- Would another section or speaker profile change the listening decision?
+
+## Caveats
+
+- This packet does not prove subjective mix quality.
+- A supported candidate proves objective receipts and guardrails only.
+- Ranking orders review; it is not a taste score.
+- Keep or apply the candidate only after listening review.