@riddledc/riddle-proof-packs 0.4.6 → 0.4.7

package/README.md

@@ -32,6 +32,12 @@ Reusable starter profile definitions and proof-pack metadata for Riddle Proof.
   - 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.
+- `createDurableCandidatePatchPlan(proofOrPacket, options)`:
+  - Validates an explicitly applied `human_review_packet` and returns a durable patch handoff plan.
+- `formatDurableCandidatePatchPlanMarkdown(plan, options)`:
+  - Formats the durable handoff without treating approval, ranking, or source application as proof of subjective taste.
+- `createDurableCandidatePatchPlanArtifacts(proofOrPacket, options)`:
+  - Returns `{ plan, json, markdown }` for storing a durable source/config handoff next to a proof run.
 
 ## Proof claims and evidence roles
 
@@ -144,6 +150,51 @@ await fs.promises.writeFile("human-review-packet.json", artifacts.json);
 await fs.promises.writeFile("human-review-packet.md", artifacts.markdown);
 ```
 
+### Durable candidate patch handoff
+
+A human-review packet is still not a source edit. Durable patch handoff is the next gate after explicit approval:
+
+1. A bounded proof loop produces a supported candidate.
+2. A human or visible surrogate approval mode sets `applyBest`.
+3. The packet reports `candidate_applied_for_listening_review`.
+4. A durable candidate plan validates that the packet is no longer transient.
+5. The app/repo applies a scoped config/source patch.
+6. A final `current_target` proof verifies the running app sees the durable state.
+
+The durable plan refuses packets that still say `candidate_ready_for_listening_review`, packets without approval metadata, packets whose `candidateActionsAreTransient` flag is still `true`, and packets that lost the listening-review caveat.
+
+From the CLI:
+
+```sh
+riddle-proof-durable-candidate-plan \
+  --proof artifacts/riddle-proof/neon-approved-candidate/proof.json \
+  --output artifacts/riddle-proof/neon-approved-candidate \
+  --source-file src/Games/songs/neon-approved-mix-overrides.json \
+  --require-mix-profile
+```
+
+This writes `durable-candidate-patch-plan.json` and `durable-candidate-patch-plan.md`. If the packet is not ready for durable application, the plan is still written with `status: "not_ready_for_durable_patch"` and the CLI exits nonzero.
+
+```ts
+import {
+  createDurableCandidatePatchPlanArtifacts,
+} from "@riddledc/riddle-proof-packs";
+
+const proof = JSON.parse(await fs.promises.readFile("proof.json", "utf8"));
+const artifacts = createDurableCandidatePatchPlanArtifacts(proof, {
+  title: "Neon Durable Candidate Patch Plan",
+  sourceFile: "src/Games/songs/neon-approved-mix-overrides.json",
+  requireMixProfileId: true,
+});
+
+if (!artifacts.plan.ok) {
+  throw new Error(`not ready for durable patch: ${artifacts.plan.errors.join(", ")}`);
+}
+
+await fs.promises.writeFile("durable-candidate-patch-plan.json", artifacts.json);
+await fs.promises.writeFile("durable-candidate-patch-plan.md", artifacts.markdown);
+```
+
 ## Usage
 
 ```ts

package/bin/riddle-proof-durable-candidate-plan

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

package/dist/chunk-VFPSPQD7.js

@@ -0,0 +1,219 @@
+import {
+  requireHumanReviewPacket
+} from "./chunk-SAE6HFAG.js";
+
+// src/durableCandidatePlan.ts
+var DEFAULT_APPROVAL_MODES = ["operator_approved", "mixing_canon_surrogate"];
+var DEFAULT_ACTION_TYPES = ["set_mixer_level"];
+var isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+var asRecord = (value) => isRecord(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 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 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 selectedTargetLabel = (packet) => {
+  const value = getPath(packet, "target.selectedSong.selectedSong") ?? getPath(packet, "target.routeState.selectedSong") ?? getPath(packet, "target.label");
+  return typeof value === "string" && value.trim() ? value : null;
+};
+var selectedRoute = (packet) => {
+  const value = getPath(packet, "target.routeState.route") ?? getPath(packet, "target.routeState.path") ?? getPath(packet, "target.route");
+  return typeof value === "string" && value.trim() ? value : null;
+};
+var selectedMixProfileId = (packet) => {
+  const value = getPath(packet, "recommendation.candidate.summary.mixProfile.id") ?? getPath(packet, "baseline.mixProfile.id") ?? getPath(packet, "target.mixProfile.id");
+  return typeof value === "string" && value.trim() ? value : null;
+};
+function createDurableCandidatePatchPlan(proofOrPacket, options = {}) {
+  const packet = requireHumanReviewPacket(proofOrPacket);
+  const recommendation = asRecord(packet.recommendation);
+  const candidate = asRecord(recommendation.candidate);
+  const action = asRecord(candidate.action);
+  const guardrails = asRecord(packet.guardrails);
+  const request = asRecord(packet.request);
+  const approval = asRecord(request.approval);
+  const ranking = asRecord(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 ${formatValue(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 ${formatValue(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: ${formatCodeValue(plan.status)}`,
+    `- ok: ${formatCodeValue(plan.ok)}`,
+    `- target_label: ${formatValue(plan.target.label)}`,
+    `- mix_profile_id: ${formatCodeValue(plan.target.mixProfileId)}`,
+    `- source_file: ${formatCodeValue(plan.durableEdit?.sourceFile)}`,
+    "",
+    "## Candidate",
+    "",
+    `- label: ${formatCodeValue(plan.candidate.label)}`,
+    `- action: ${formatCodeValue(`${formatValue(plan.candidate.action.type)} ${formatValue(plan.candidate.action.track)}: ${formatValue(plan.candidate.action.from)} -> ${formatValue(plan.candidate.action.to)} (${formatValue(plan.candidate.action.delta)})`)}`,
+    "",
+    "## Approval Boundary",
+    "",
+    `- approval_mode: ${formatCodeValue(plan.approval.mode)}`,
+    `- approved_by: ${formatCodeValue(plan.approval.approvedBy)}`,
+    `- basis: ${formatValue(plan.approval.basis)}`,
+    `- boundary: ${formatValue(plan.boundary)}`,
+    "",
+    "## Durable Edit",
+    "",
+    `- mixer_levels: ${formatCodeValue(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
+  };
+}
+
+export {
+  createDurableCandidatePatchPlan,
+  formatDurableCandidatePatchPlanMarkdown,
+  createDurableCandidatePatchPlanArtifacts
+};

package/dist/durableCandidatePlan-Dv2P33Wg.d.cts

@@ -0,0 +1,77 @@
+interface DurableCandidatePatchPlanOptions {
+    title?: string;
+    sourceFile?: string;
+    requireTargetLabel?: boolean;
+    requireMixProfileId?: boolean;
+    allowedApprovalModes?: readonly string[];
+    allowedActionTypes?: readonly string[];
+}
+interface DurableCandidatePatchPlanArtifacts {
+    plan: DurableCandidatePatchPlan;
+    json: string;
+    markdown: string;
+}
+type DurableCandidatePatchPlan = {
+    version: "riddle-proof.durable-candidate-patch-plan.v1";
+    kind: "durable_candidate_patch_plan";
+    status: "ready_for_durable_patch" | "not_ready_for_durable_patch";
+    ok: boolean;
+    errors: string[];
+    source: {
+        packetStatus: unknown;
+        recommendationAction: unknown;
+        rankingRole: unknown;
+        proofBoundary: unknown;
+    };
+    target: {
+        label: string | null;
+        route: string | null;
+        mixProfileId: string | null;
+    };
+    candidate: {
+        label: unknown;
+        action: {
+            type: unknown;
+            track: unknown;
+            from: number | null;
+            to: number | null;
+            delta: number | null;
+        };
+    };
+    approval: {
+        mode: unknown;
+        approvedBy: unknown;
+        basis: unknown;
+    };
+    durableEdit: null | {
+        sourceFile: string | null;
+        target: {
+            label: string | null;
+            route: string | null;
+            mixProfileId: string | null;
+        };
+        action: {
+            type: unknown;
+            track: unknown;
+            from: number | null;
+            to: number | null;
+            delta: number | null;
+        };
+        mixerLevels: Record<string, number> | null;
+        provenance: {
+            humanReviewPacketStatus: unknown;
+            recommendationLabel: unknown;
+            approvalMode: unknown;
+            approvedBy: unknown;
+            basis: unknown;
+        };
+        doesNotProve: string[];
+    };
+    boundary: string;
+    caveats: string[];
+};
+declare function createDurableCandidatePatchPlan(proofOrPacket: unknown, options?: DurableCandidatePatchPlanOptions): DurableCandidatePatchPlan;
+declare function formatDurableCandidatePatchPlanMarkdown(plan: DurableCandidatePatchPlan, options?: Pick<DurableCandidatePatchPlanOptions, "title">): string;
+declare function createDurableCandidatePatchPlanArtifacts(proofOrPacket: unknown, options?: DurableCandidatePatchPlanOptions): DurableCandidatePatchPlanArtifacts;
+
+export { type DurableCandidatePatchPlan as D, type DurableCandidatePatchPlanArtifacts as a, type DurableCandidatePatchPlanOptions as b, createDurableCandidatePatchPlan as c, createDurableCandidatePatchPlanArtifacts as d, formatDurableCandidatePatchPlanMarkdown as f };

package/dist/durableCandidatePlan-Dv2P33Wg.d.ts

@@ -0,0 +1,77 @@
+interface DurableCandidatePatchPlanOptions {
+    title?: string;
+    sourceFile?: string;
+    requireTargetLabel?: boolean;
+    requireMixProfileId?: boolean;
+    allowedApprovalModes?: readonly string[];
+    allowedActionTypes?: readonly string[];
+}
+interface DurableCandidatePatchPlanArtifacts {
+    plan: DurableCandidatePatchPlan;
+    json: string;
+    markdown: string;
+}
+type DurableCandidatePatchPlan = {
+    version: "riddle-proof.durable-candidate-patch-plan.v1";
+    kind: "durable_candidate_patch_plan";
+    status: "ready_for_durable_patch" | "not_ready_for_durable_patch";
+    ok: boolean;
+    errors: string[];
+    source: {
+        packetStatus: unknown;
+        recommendationAction: unknown;
+        rankingRole: unknown;
+        proofBoundary: unknown;
+    };
+    target: {
+        label: string | null;
+        route: string | null;
+        mixProfileId: string | null;
+    };
+    candidate: {
+        label: unknown;
+        action: {
+            type: unknown;
+            track: unknown;
+            from: number | null;
+            to: number | null;
+            delta: number | null;
+        };
+    };
+    approval: {
+        mode: unknown;
+        approvedBy: unknown;
+        basis: unknown;
+    };
+    durableEdit: null | {
+        sourceFile: string | null;
+        target: {
+            label: string | null;
+            route: string | null;
+            mixProfileId: string | null;
+        };
+        action: {
+            type: unknown;
+            track: unknown;
+            from: number | null;
+            to: number | null;
+            delta: number | null;
+        };
+        mixerLevels: Record<string, number> | null;
+        provenance: {
+            humanReviewPacketStatus: unknown;
+            recommendationLabel: unknown;
+            approvalMode: unknown;
+            approvedBy: unknown;
+            basis: unknown;
+        };
+        doesNotProve: string[];
+    };
+    boundary: string;
+    caveats: string[];
+};
+declare function createDurableCandidatePatchPlan(proofOrPacket: unknown, options?: DurableCandidatePatchPlanOptions): DurableCandidatePatchPlan;
+declare function formatDurableCandidatePatchPlanMarkdown(plan: DurableCandidatePatchPlan, options?: Pick<DurableCandidatePatchPlanOptions, "title">): string;
+declare function createDurableCandidatePatchPlanArtifacts(proofOrPacket: unknown, options?: DurableCandidatePatchPlanOptions): DurableCandidatePatchPlanArtifacts;
+
+export { type DurableCandidatePatchPlan as D, type DurableCandidatePatchPlanArtifacts as a, type DurableCandidatePatchPlanOptions as b, createDurableCandidatePatchPlan as c, createDurableCandidatePatchPlanArtifacts as d, formatDurableCandidatePatchPlanMarkdown as f };