@claudexor/synthesis 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 joi-lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @claudexor/synthesis
+
+Internal package of [Claudexor](https://github.com/razzant/claudexor) — Synthesis decision + plan: when to merge candidates into a new (re-checked) candidate.
+
+Published as part of the Claudexor toolchain; it follows the monorepo's
+lockstep version and has no separate semver contract. Use the `claudexor`
+CLI (or `@claudexor/cli`) as the supported entry point.

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import type { CandidateEvidence } from "@claudexor/arbitration";
+export type SynthesisMode = "auto" | "always" | "never";
+export interface SynthesisDecision {
+    synthesize: boolean;
+    reason: string;
+    sources: string[];
+}
+/**
+ * Auto mode only synthesizes a 3rd candidate when there are at least this many
+ * candidates. best-of-2 just picks the winner: synthesizing on n=2 adds a 3rd
+ * paid harness run + a 3rd full review pass (~3x cost) for marginal benefit.
+ * `--synthesis always` overrides this; `never` disables.
+ */
+export declare const AUTO_SYNTHESIS_MIN_CANDIDATES = 3;
+/**
+ * Decide whether synthesizing a new candidate is worthwhile. Auto mode
+ * synthesizes (when >= AUTO_SYNTHESIS_MIN_CANDIDATES) if there is no clear
+ * winner, the best candidate has fixable accepted findings, or candidates have
+ * complementary strengths. A single clearly-winning candidate — and any n<3
+ * auto race — is NOT synthesized.
+ */
+export declare function decideSynthesis(candidates: CandidateEvidence[], mode?: SynthesisMode): SynthesisDecision;
+export interface SynthesisPlan {
+    baseFrom: string;
+    borrowTestsFrom: string | null;
+    fixFindings: string[];
+    instructions: string;
+}
+/**
+ * Build a plan for the synthesizer harness. The synthesized output MUST then be
+ * re-run through gates + review + revalidation + arbitration as a new candidate
+ * (never applied unchecked, never a blind diff concatenation).
+ */
+export declare function buildSynthesisPlan(candidates: CandidateEvidence[]): SynthesisPlan;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAGhE,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAExD,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAID;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAE/C;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,iBAAiB,EAAE,EAAE,IAAI,GAAE,aAAsB,GAAG,iBAAiB,CAiDhH;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,iBAAiB,EAAE,GAAG,aAAa,CA0BjF"}

package/dist/index.js

@@ -0,0 +1,88 @@
+import { candidateSummary, compareCandidates } from "@claudexor/arbitration";
+const FIXABLE_STATUSES = new Set(["accepted", "accepted_risk"]);
+/**
+ * Auto mode only synthesizes a 3rd candidate when there are at least this many
+ * candidates. best-of-2 just picks the winner: synthesizing on n=2 adds a 3rd
+ * paid harness run + a 3rd full review pass (~3x cost) for marginal benefit.
+ * `--synthesis always` overrides this; `never` disables.
+ */
+export const AUTO_SYNTHESIS_MIN_CANDIDATES = 3;
+/**
+ * Decide whether synthesizing a new candidate is worthwhile. Auto mode
+ * synthesizes (when >= AUTO_SYNTHESIS_MIN_CANDIDATES) if there is no clear
+ * winner, the best candidate has fixable accepted findings, or candidates have
+ * complementary strengths. A single clearly-winning candidate — and any n<3
+ * auto race — is NOT synthesized.
+ */
+export function decideSynthesis(candidates, mode = "auto") {
+    if (mode === "never")
+        return { synthesize: false, reason: "synthesis disabled", sources: [] };
+    if (candidates.length < 2) {
+        return { synthesize: false, reason: "need >= 2 candidates to synthesize", sources: candidates.map((c) => c.attemptId) };
+    }
+    if (mode === "always") {
+        return { synthesize: true, reason: "synthesis forced (always)", sources: candidates.map((c) => c.attemptId) };
+    }
+    if (candidates.length < AUTO_SYNTHESIS_MIN_CANDIDATES) {
+        return {
+            synthesize: false,
+            reason: `auto synthesis needs >= ${AUTO_SYNTHESIS_MIN_CANDIDATES} candidates (best-of-${candidates.length} picks the winner)`,
+            sources: candidates.map((c) => c.attemptId),
+        };
+    }
+    const ranked = [...candidates].sort(compareCandidates);
+    const top = ranked[0];
+    const second = ranked[1];
+    const ts = candidateSummary(top);
+    const ss = candidateSummary(second);
+    const strictlyBetter = compareCandidates(top, second) < 0;
+    const clearWinner = ts.gatesPassed && ts.clean && ts.blockers === 0 && strictlyBetter;
+    const topFixable = top.findings.some((f) => FIXABLE_STATUSES.has(f.status));
+    // Only a GREEN runner-up can contribute complementary strengths: a failed
+    // candidate with an empty diff is not "simpler", and synthesizing against it
+    // wastes a paid run plus a full review pass.
+    const complementary = ss.gatesPassed &&
+        (ss.testFraction > ts.testFraction ||
+            ss.acceptance > ts.acceptance ||
+            ss.blockers < ts.blockers ||
+            (second.diffSize ?? 0) < (top.diffSize ?? 0)); // second is simpler on a lower-priority axis
+    if (clearWinner && !topFixable && !complementary) {
+        return { synthesize: false, reason: "a single candidate clearly passes all gates and review", sources: [top.attemptId] };
+    }
+    const reasons = [];
+    if (!clearWinner)
+        reasons.push("no clear winner");
+    if (topFixable)
+        reasons.push("best candidate has fixable accepted findings");
+    if (complementary)
+        reasons.push("candidates have complementary strengths");
+    return {
+        synthesize: true,
+        reason: reasons.join("; "),
+        sources: ranked.slice(0, Math.min(3, ranked.length)).map((c) => c.attemptId),
+    };
+}
+/**
+ * Build a plan for the synthesizer harness. The synthesized output MUST then be
+ * re-run through gates + review + revalidation + arbitration as a new candidate
+ * (never applied unchecked, never a blind diff concatenation).
+ */
+export function buildSynthesisPlan(candidates) {
+    const ranked = [...candidates].sort(compareCandidates);
+    const base = ranked[0];
+    const bestTests = [...candidates].sort((a, b) => candidateSummary(b).testFraction - candidateSummary(a).testFraction)[0];
+    const fixFindings = [
+        ...new Set(candidates.flatMap((c) => c.findings.filter((f) => FIXABLE_STATUSES.has(f.status)).map((f) => f.claim))),
+    ];
+    const borrowTestsFrom = bestTests.attemptId !== base.attemptId ? bestTests.attemptId : null;
+    const instructions = [
+        `Start from ${base.label}.`,
+        borrowTestsFrom ? `Use the stronger gate/test results from ${bestTests.label} as evidence, but do not edit protected tests or gate configuration unless the user explicitly asked for test changes.` : "",
+        fixFindings.length > 0 ? `Fix the accepted findings (${fixFindings.length}).` : "",
+        "Produce a single coherent patch; do not blindly concatenate diffs. The result will be re-reviewed.",
+    ]
+        .filter(Boolean)
+        .join(" ");
+    return { baseFrom: base.attemptId, borrowTestsFrom, fixFindings, instructions };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@claudexor/synthesis",
+  "version": "1.0.0",
+  "license": "MIT",
+  "description": "Synthesis decision + plan: when to merge candidates into a new (re-checked) candidate.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@claudexor/arbitration": "1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/razzant/claudexor.git",
+    "directory": "packages/synthesis"
+  },
+  "homepage": "https://github.com/razzant/claudexor#readme",
+  "bugs": {
+    "url": "https://github.com/razzant/claudexor/issues"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  }
+}