@riddledc/riddle-proof-packs 0.4.5 → 0.4.7

package/dist/index.cjs

@@ -22,8 +22,11 @@ var index_exports = {};
 __export(index_exports, {
   RIDDLE_PROOF_PACK_MANIFEST: () => RIDDLE_PROOF_PACK_MANIFEST,
   RIDDLE_PROOF_PACK_PROFILES: () => RIDDLE_PROOF_PACK_PROFILES,
+  createDurableCandidatePatchPlan: () => createDurableCandidatePatchPlan,
+  createDurableCandidatePatchPlanArtifacts: () => createDurableCandidatePatchPlanArtifacts,
   createHumanReviewPacketArtifacts: () => createHumanReviewPacketArtifacts,
   findHumanReviewPacket: () => findHumanReviewPacket,
+  formatDurableCandidatePatchPlanMarkdown: () => formatDurableCandidatePatchPlanMarkdown,
   formatHumanReviewPacketMarkdown: () => formatHumanReviewPacketMarkdown,
   getPackEnabledRiddleProofPackProfiles: () => getPackEnabledRiddleProofPackProfiles,
   getRiddleProofPackProfile: () => getRiddleProofPackProfile,
@@ -1656,6 +1659,185 @@ var playback_sync_default = {
   }
 };
 
+// packs/neon-step-sequencer/profiles/ratchet-loop-approved-candidate.json
+var ratchet_loop_approved_candidate_default = {
+  version: "riddle-proof.profile.v1",
+  name: "neon-step-sequencer-ratchet-loop-approved-candidate",
+  target: {
+    route: "/games/drum-sequencer?song=monkberry-moon-delight-tab&mix=profile&view=trainer&instrument=bass",
+    viewports: [
+      {
+        name: "desktop",
+        width: 1440,
+        height: 1e3
+      }
+    ],
+    timeout_sec: 360,
+    wait_for_selector: ".drum-sequencer h1",
+    setup_actions: [
+      {
+        type: "window_eval",
+        label: "capture-neon-contract",
+        timeout_ms: 1e4,
+        store_return_to: "__neonMixProof.contract",
+        script: "const contract=window.__NEON_MIX_PROOF__; const diagnostic=contract?.captureDiagnostic?.(); window.__neonMixProof={...(window.__neonMixProof||{}),contract:{available:Boolean(contract),diagnostic}}; return window.__neonMixProof.contract;",
+        return_summary_fields: [
+          {
+            path: "available"
+          },
+          {
+            path: "diagnostic.selectedSong.selectedSong"
+          }
+        ]
+      },
+      {
+        type: "assert_window_value",
+        path: "__neonMixProof.contract.available",
+        expected_value: true,
+        timeout_ms: 1e4
+      },
+      {
+        type: "window_call",
+        label: "apply-approved-claim-candidate",
+        path: "__NEON_MIX_PROOF__.runRatchetLoop",
+        args: [
+          {
+            intent: "turn the chord part down a little",
+            strategy: "mix-level-search",
+            focusTracks: [
+              "bass",
+              "chord",
+              "guitar",
+              "rhythmSynth"
+            ],
+            maxIterations: 6,
+            monitorProfile: "smallSpeaker",
+            restore: true,
+            applyBest: true,
+            approval: {
+              mode: "mixing_canon_surrogate",
+              approvedBy: "codex",
+              basis: "subtle level reduction after objective receipts pass; this keeps development moving while preserving a listening-review caveat"
+            }
+          }
+        ],
+        store_return_to: "__neonMixProof.approvedCandidateLoop",
+        capture_return: true,
+        timeout_ms: 24e4,
+        return_summary_fields: [
+          {
+            path: "ok"
+          },
+          {
+            path: "status"
+          },
+          {
+            path: "best.claimVerdict.status"
+          },
+          {
+            path: "best.claimCandidate.action.track"
+          },
+          {
+            path: "appliedCandidateReceipt.ok"
+          },
+          {
+            path: "humanReviewPacket.status"
+          },
+          {
+            path: "humanReviewPacket.request.approval.mode"
+          },
+          {
+            path: "humanReviewPacket.ranking.role"
+          }
+        ]
+      },
+      {
+        type: "assert_window_value",
+        path: "__neonMixProof.approvedCandidateLoop.ok",
+        expected_value: true,
+        timeout_ms: 1e4
+      },
+      {
+        type: "assert_window_value",
+        path: "__neonMixProof.approvedCandidateLoop.appliedCandidateReceipt.ok",
+        expected_value: true,
+        timeout_ms: 1e4
+      },
+      {
+        type: "assert_window_value",
+        path: "__neonMixProof.approvedCandidateLoop.humanReviewPacket.status",
+        expected_value: "candidate_applied_for_listening_review",
+        timeout_ms: 1e4
+      },
+      {
+        type: "assert_window_value",
+        path: "__neonMixProof.approvedCandidateLoop.humanReviewPacket.request.candidateActionsAreTransient",
+        expected_value: false,
+        timeout_ms: 1e4
+      },
+      {
+        type: "assert_window_value",
+        path: "__neonMixProof.approvedCandidateLoop.humanReviewPacket.guardrails.approvedCandidateApplied",
+        expected_value: true,
+        timeout_ms: 1e4
+      },
+      {
+        type: "screenshot",
+        label: "neon-step-sequencer-ratchet-loop-approved-candidate",
+        mode: "viewport"
+      }
+    ]
+  },
+  checks: [
+    {
+      type: "route_loaded",
+      expected_path: "/games/drum-sequencer"
+    },
+    {
+      type: "selector_visible",
+      selector: ".drum-sequencer h1"
+    },
+    {
+      type: "no_horizontal_overflow"
+    },
+    {
+      type: "no_fatal_console_errors"
+    }
+  ],
+  artifacts: [
+    "screenshot",
+    "console",
+    "dom_summary",
+    "proof_json"
+  ],
+  baseline_policy: "invariant_only",
+  failure_policy: {
+    environment_blocked: "neutral",
+    proof_insufficient: "review",
+    needs_human_review: "review",
+    product_regression: "fail"
+  },
+  metadata: {
+    pack_id: "neon_step_sequencer",
+    pack_public_name: "Neon Step Sequencer Pack",
+    evidence_role_pattern: "interaction_snapshots",
+    purpose: "Run a bounded loop, use an explicit operator-approval surrogate, apply the supported claim candidate, and preserve a listening-review packet.",
+    required_receipts: [
+      "ratchet loop returns ok",
+      "a supported claim candidate is selected",
+      "approved candidate application receipt is captured",
+      "compact human-review packet is captured",
+      "ranking remains review-order only",
+      "listening-review caveat remains explicit"
+    ],
+    does_not_prove: [
+      "subjective mix quality",
+      "that the approval surrogate is a real listener preference",
+      "all possible mix edits"
+    ]
+  }
+};
+
 // packs/neon-step-sequencer/profiles/ratchet-loop-mix-level-search.json
 var ratchet_loop_mix_level_search_default = {
   version: "riddle-proof.profile.v1",
@@ -2258,7 +2440,8 @@ var rawProfiles = {
   "neon-step-sequencer-mobile-trainer-layout": mobile_trainer_layout_default,
   "neon-step-sequencer-full-mix-health-matrix": full_mix_health_matrix_default,
   "neon-step-sequencer-explore-songs-and-mixes": explore_songs_and_mixes_default,
-  "neon-step-sequencer-ratchet-loop-mix-level-search": ratchet_loop_mix_level_search_default
+  "neon-step-sequencer-ratchet-loop-mix-level-search": ratchet_loop_mix_level_search_default,
+  "neon-step-sequencer-ratchet-loop-approved-candidate": ratchet_loop_approved_candidate_default
 };
 var sourcePathOverrides = Object.freeze({
   "neon-step-sequencer-fast-mix-health": "packs/neon-step-sequencer/profiles/fast-mix-health.json",
@@ -2268,7 +2451,8 @@ var sourcePathOverrides = Object.freeze({
   "neon-step-sequencer-mobile-trainer-layout": "packs/neon-step-sequencer/profiles/mobile-trainer-layout.json",
   "neon-step-sequencer-full-mix-health-matrix": "packs/neon-step-sequencer/profiles/full-mix-health-matrix.json",
   "neon-step-sequencer-explore-songs-and-mixes": "packs/neon-step-sequencer/profiles/explore-songs-and-mixes.json",
-  "neon-step-sequencer-ratchet-loop-mix-level-search": "packs/neon-step-sequencer/profiles/ratchet-loop-mix-level-search.json"
+  "neon-step-sequencer-ratchet-loop-mix-level-search": "packs/neon-step-sequencer/profiles/ratchet-loop-mix-level-search.json",
+  "neon-step-sequencer-ratchet-loop-approved-candidate": "packs/neon-step-sequencer/profiles/ratchet-loop-approved-candidate.json"
 });
 var RIDDLE_PROOF_PACK_PROFILES = Object.freeze(
   Object.fromEntries(
@@ -2415,6 +2599,7 @@ function formatHumanReviewPacketMarkdown(packet, options = {}) {
   const guardrails = asRecord(packet.guardrails) ?? {};
   const ranking = asRecord(packet.ranking) ?? {};
   const request = asRecord(packet.request) ?? {};
+  const approval = asRecord(request.approval) ?? {};
   const supportedCandidates = asArray(packet.supportedCandidates);
   const rejectedCandidates = asArray(packet.rejectedCandidates);
   const selectedSong = getPath(packet, "target.selectedSong.selectedSong") ?? getPath(packet, "target.routeState.selectedSong");
@@ -2441,6 +2626,9 @@ function formatHumanReviewPacketMarkdown(packet, options = {}) {
     `- state_restored_after_loop: ${formatCodeValue(guardrails.stateRestoredAfterLoop)}`,
     `- candidate_actions_are_transient: ${formatCodeValue(request.candidateActionsAreTransient)}`,
     `- no_permanent_edit_unless_apply_best: ${formatCodeValue(guardrails.noPermanentEditUnlessApplyBest)}`,
+    `- approved_candidate_applied: ${formatCodeValue(guardrails.approvedCandidateApplied)}`,
+    `- approval_mode: ${formatCodeValue(approval.mode)}`,
+    `- approval_basis: ${formatValue(approval.basis)}`,
     "",
     "## Ranking",
     "",
@@ -2478,12 +2666,225 @@ function createHumanReviewPacketArtifacts(proofOrPacket, options = {}) {
     markdown
   };
 }
+
+// src/durableCandidatePlan.ts
+var DEFAULT_APPROVAL_MODES = ["operator_approved", "mixing_canon_surrogate"];
+var DEFAULT_ACTION_TYPES = ["set_mixer_level"];
+var isRecord3 = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+var asRecord2 = (value) => isRecord3(value) ? value : {};
+var getPath2 = (value, path) => {
+  let cursor = value;
+  for (const part of path.split(".")) {
+    if (!isRecord3(cursor)) return void 0;
+    cursor = cursor[part];
+  }
+  return cursor;
+};
+var asFiniteNumber = (value) => {
+  if (value === null || value === void 0 || value === "") return null;
+  if (typeof value !== "number" && typeof value !== "string") return null;
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? Number(numeric.toFixed(4)) : null;
+};
+var formatValue2 = (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 formatCodeValue2 = (value) => `\`${formatValue2(value)}\``;
+var selectedTargetLabel = (packet) => {
+  const value = getPath2(packet, "target.selectedSong.selectedSong") ?? getPath2(packet, "target.routeState.selectedSong") ?? getPath2(packet, "target.label");
+  return typeof value === "string" && value.trim() ? value : null;
+};
+var selectedRoute = (packet) => {
+  const value = getPath2(packet, "target.routeState.route") ?? getPath2(packet, "target.routeState.path") ?? getPath2(packet, "target.route");
+  return typeof value === "string" && value.trim() ? value : null;
+};
+var selectedMixProfileId = (packet) => {
+  const value = getPath2(packet, "recommendation.candidate.summary.mixProfile.id") ?? getPath2(packet, "baseline.mixProfile.id") ?? getPath2(packet, "target.mixProfile.id");
+  return typeof value === "string" && value.trim() ? value : null;
+};
+function createDurableCandidatePatchPlan(proofOrPacket, options = {}) {
+  const packet = requireHumanReviewPacket(proofOrPacket);
+  const recommendation = asRecord2(packet.recommendation);
+  const candidate = asRecord2(recommendation.candidate);
+  const action = asRecord2(candidate.action);
+  const guardrails = asRecord2(packet.guardrails);
+  const request = asRecord2(packet.request);
+  const approval = asRecord2(request.approval);
+  const ranking = asRecord2(packet.ranking);
+  const proofBoundary = packet.proofBoundary;
+  const target = {
+    label: selectedTargetLabel(packet),
+    route: selectedRoute(packet),
+    mixProfileId: selectedMixProfileId(packet)
+  };
+  const actionType = action.type;
+  const actionTrack = action.track;
+  const from = asFiniteNumber(action.from);
+  const to = asFiniteNumber(action.to);
+  const numericDelta = asFiniteNumber(action.delta);
+  const delta = numericDelta ?? (from !== null && to !== null ? asFiniteNumber(to - from) : null);
+  const allowedApprovalModes = new Set(options.allowedApprovalModes ?? DEFAULT_APPROVAL_MODES);
+  const allowedActionTypes = new Set(options.allowedActionTypes ?? DEFAULT_ACTION_TYPES);
+  const errors = [];
+  if (packet.status !== "candidate_applied_for_listening_review") {
+    errors.push("packet status must be candidate_applied_for_listening_review");
+  }
+  if (recommendation.action !== "listen_to_applied_candidate") {
+    errors.push("recommendation action must be listen_to_applied_candidate");
+  }
+  if (guardrails.approvedCandidateApplied !== true) {
+    errors.push("approvedCandidateApplied guardrail must be true");
+  }
+  if (request.candidateActionsAreTransient !== false) {
+    errors.push("candidateActionsAreTransient must be false before a durable patch handoff");
+  }
+  if (!approval.mode) {
+    errors.push("approval mode is required");
+  } else if (!allowedApprovalModes.has(String(approval.mode))) {
+    errors.push(`approval mode ${formatValue2(approval.mode)} is not allowed for durable patch handoff`);
+  }
+  if (ranking.role !== "review_order_only") {
+    errors.push("ranking role must remain review_order_only");
+  }
+  if (!String(proofBoundary ?? "").includes("musical taste still requires listening review")) {
+    errors.push("proof boundary must preserve the listening-review caveat");
+  }
+  if (!actionType || !allowedActionTypes.has(String(actionType))) {
+    errors.push(`action type ${formatValue2(actionType)} is not allowed for durable patch handoff`);
+  }
+  if (typeof actionTrack !== "string" || !actionTrack.trim()) {
+    errors.push("candidate action track is required");
+  }
+  if (to === null) {
+    errors.push("candidate action target value is required");
+  }
+  if (String(actionType) === "set_mixer_level" && (to === null || to < 0 || to > 1.5)) {
+    errors.push("set_mixer_level target must be between 0 and 1.5");
+  }
+  if (options.requireTargetLabel !== false && !target.label) {
+    errors.push("target label is required for a scoped durable patch handoff");
+  }
+  if (options.requireMixProfileId === true && !target.mixProfileId) {
+    errors.push("mixProfileId is required for this durable patch handoff");
+  }
+  const actionShape = {
+    type: actionType ?? null,
+    track: actionTrack ?? null,
+    from,
+    to,
+    delta
+  };
+  const mixerLevels = !errors.length && String(actionType) === "set_mixer_level" && typeof actionTrack === "string" && to !== null ? { [actionTrack]: to } : null;
+  return {
+    version: "riddle-proof.durable-candidate-patch-plan.v1",
+    kind: "durable_candidate_patch_plan",
+    status: errors.length ? "not_ready_for_durable_patch" : "ready_for_durable_patch",
+    ok: errors.length === 0,
+    errors,
+    source: {
+      packetStatus: packet.status ?? null,
+      recommendationAction: recommendation.action ?? null,
+      rankingRole: ranking.role ?? null,
+      proofBoundary: proofBoundary ?? null
+    },
+    target,
+    candidate: {
+      label: candidate.label ?? null,
+      action: actionShape
+    },
+    approval: {
+      mode: approval.mode ?? null,
+      approvedBy: approval.approvedBy ?? null,
+      basis: approval.basis ?? null
+    },
+    durableEdit: errors.length ? null : {
+      sourceFile: options.sourceFile ?? null,
+      target,
+      action: actionShape,
+      mixerLevels,
+      provenance: {
+        humanReviewPacketStatus: packet.status ?? null,
+        recommendationLabel: candidate.label ?? null,
+        approvalMode: approval.mode ?? null,
+        approvedBy: approval.approvedBy ?? null,
+        basis: approval.basis ?? null
+      },
+      doesNotProve: [
+        "subjective mix quality",
+        "that the approval surrogate is a real listener preference",
+        "all possible candidate edits"
+      ]
+    },
+    boundary: "This is a durable patch handoff for an approved listening-review candidate. It does not prove subjective mix quality.",
+    caveats: [
+      "A durable patch plan is not a taste verdict.",
+      "Ranking orders review only; it is not a universal mix-quality score.",
+      "Run a final current-target proof after the durable edit lands."
+    ]
+  };
+}
+function formatDurableCandidatePatchPlanMarkdown(plan, options = {}) {
+  if (plan.kind !== "durable_candidate_patch_plan") {
+    throw new Error("Expected a durable_candidate_patch_plan");
+  }
+  const lines = [
+    `# ${options.title ?? "Durable Candidate Patch Plan"}`,
+    "",
+    `- status: ${formatCodeValue2(plan.status)}`,
+    `- ok: ${formatCodeValue2(plan.ok)}`,
+    `- target_label: ${formatValue2(plan.target.label)}`,
+    `- mix_profile_id: ${formatCodeValue2(plan.target.mixProfileId)}`,
+    `- source_file: ${formatCodeValue2(plan.durableEdit?.sourceFile)}`,
+    "",
+    "## Candidate",
+    "",
+    `- label: ${formatCodeValue2(plan.candidate.label)}`,
+    `- action: ${formatCodeValue2(`${formatValue2(plan.candidate.action.type)} ${formatValue2(plan.candidate.action.track)}: ${formatValue2(plan.candidate.action.from)} -> ${formatValue2(plan.candidate.action.to)} (${formatValue2(plan.candidate.action.delta)})`)}`,
+    "",
+    "## Approval Boundary",
+    "",
+    `- approval_mode: ${formatCodeValue2(plan.approval.mode)}`,
+    `- approved_by: ${formatCodeValue2(plan.approval.approvedBy)}`,
+    `- basis: ${formatValue2(plan.approval.basis)}`,
+    `- boundary: ${formatValue2(plan.boundary)}`,
+    "",
+    "## Durable Edit",
+    "",
+    `- mixer_levels: ${formatCodeValue2(JSON.stringify(plan.durableEdit?.mixerLevels ?? null))}`
+  ];
+  if (plan.errors.length) {
+    lines.push("", "## Errors", "");
+    for (const error of plan.errors) lines.push(`- ${error}`);
+  }
+  lines.push("", "## Caveats", "");
+  for (const caveat of plan.caveats) lines.push(`- ${caveat}`);
+  return `${lines.join("\n")}
+`;
+}
+function createDurableCandidatePatchPlanArtifacts(proofOrPacket, options = {}) {
+  const plan = createDurableCandidatePatchPlan(proofOrPacket, options);
+  const markdown = formatDurableCandidatePatchPlanMarkdown(plan, {
+    title: options.title
+  });
+  return {
+    plan,
+    json: `${JSON.stringify(plan, null, 2)}
+`,
+    markdown
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   RIDDLE_PROOF_PACK_MANIFEST,
   RIDDLE_PROOF_PACK_PROFILES,
+  createDurableCandidatePatchPlan,
+  createDurableCandidatePatchPlanArtifacts,
   createHumanReviewPacketArtifacts,
   findHumanReviewPacket,
+  formatDurableCandidatePatchPlanMarkdown,
   formatHumanReviewPacketMarkdown,
   getPackEnabledRiddleProofPackProfiles,
   getRiddleProofPackProfile,

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 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';
+export { D as DurableCandidatePatchPlan, a as DurableCandidatePatchPlanArtifacts, b as DurableCandidatePatchPlanOptions, c as createDurableCandidatePatchPlan, d as createDurableCandidatePatchPlanArtifacts, f as formatDurableCandidatePatchPlanMarkdown } from './durableCandidatePlan-Dv2P33Wg.cjs';
 
 interface RiddleProofPackProfileManifest {
     /** Profile slug and canonical manifest key. */

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 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';
+export { D as DurableCandidatePatchPlan, a as DurableCandidatePatchPlanArtifacts, b as DurableCandidatePatchPlanOptions, c as createDurableCandidatePatchPlan, d as createDurableCandidatePatchPlanArtifacts, f as formatDurableCandidatePatchPlanMarkdown } from './durableCandidatePlan-Dv2P33Wg.js';
 
 interface RiddleProofPackProfileManifest {
     /** Profile slug and canonical manifest key. */