renkin 0.60.0 → 1.0.0

package/README.md

@@ -47,7 +47,7 @@ npm install renkin          # JavaScript (browser / bundler -- see docs/api/wasm
 
 Auditing Syntheseus routes needs one more, optional package:
 `pip install renkin[syntheseus]` (verified against Syntheseus `0.7.2` and
-`0.8.0` — see the [compatibility spike](https://github.com/kent-tokyo/renkin/blob/master/docs/design/syntheseus-0.8-compatibility-spike.md)).
+`0.8.0`).
 
 ---
 
@@ -73,6 +73,11 @@ report = json.loads(
 print(report["summary"])
 ```
 
+For an evidence-boundary report, add `--chemical-review` to
+`renkin audit-route ... --output json`. The optional report is deterministic;
+missing conditions, selectivity, and substrate-scope evidence remain
+`not_evaluable`. See the [chemical review rubric](https://kent-tokyo.github.io/renkin/guides/chemical-review-rubric/).
+
 **Syntheseus** (`pip install renkin[syntheseus]`)
 
 ```python
@@ -409,7 +414,7 @@ for the full acceptance criteria and licensing split.
 | **Route scoring** | `confidence`, `step_confidence`, `success_probability` (Retro-prob style), `convergency`, `atom_economy`, `route_cost` (`Σ BB cost + steps×0.5`, or actual prices via `--bb-prices`/`--stock`) per step/route — see caveat below the table |
 | **Step metadata provenance** | Each step reports `metadata_source`/`metadata_scope` so it's machine-readable whether `conditions`/`reaction_family` came from a rule-author default vs. something more grounded; absent (not fabricated) for extracted templates |
 | **Pareto multi-objective search** | `--format pareto` returns a Pareto front across `route_cost`/`success_probability`/`steps`; objectives configurable via `--objectives` |
-| **Constraint DSL** | `--constraints constraints.json` — element filters, step limits, confidence thresholds, preferred reaction families; enables LLM → RENKIN pipelines |
+| **Constraint DSL** | `--constraints constraints.json` — element/building-block filters, step/cost limits, confidence thresholds, required/avoided/preferred reaction families; enables LLM → RENKIN pipelines |
 | **Output formats & diagnostics** | `--format json\|tree\|mermaid\|explain\|compare\|compare-json\|pareto`; zero-route JSON includes a `diagnostics` block with `likely_causes`/`suggestions` |
 | **`renkin-forward` toolkit** | `predict` (rank forward products), `enumerate` (bounded products from one reactant + partner library), `hints` (partner-free retrieval hints, no concrete product), `validate` (forward-verify each retro step) — see the [Forward guides](docs/guides/forward-retrieval-hints.md#predict--enumerate--hints-at-a-glance) |
 | **`renkin-bench`** | USPTO-50k/PaRoutes evaluation with `--plausibility` (forward-validated composite score), `--failure-taxonomy`, atom-balance checks (`target_MW > Σ precursor_MW`), and multi-stage `cascade` re-runs on unsolved targets — see [Benchmark](#benchmark) |
@@ -560,7 +565,7 @@ The JSON output includes `avg_nodes_expanded`, `avg_confidence`, `avg_convergenc
 | `validate_route` | Forward-validate a retrosynthetic route |
 | `explain_route` | Human-readable strengths/weaknesses per route |
 | `find_pareto_routes` | Pareto-front multi-objective route search |
-| `plan_with_constraints` | Constraint-DSL planning (element filters, step limits, confidence thresholds) |
+| `plan_with_constraints` | Constraint-DSL planning (element/building-block filters, step/cost limits, confidence thresholds, required/avoided/preferred reaction families) |
 | `estimate_diversity` | Route diversity and coverage metrics |
 
 `find_routes` also accepts `search_mode: "coverage"` with a required
@@ -568,7 +573,7 @@ The JSON output includes `avg_nodes_expanded`, `avg_confidence`, `avg_convergenc
 to Stage 2 only when Stage 1 finds no route; the response reports the selected
 stage, timeout status, and per-stage elapsed time.
 
-The server auto-detects `data/building_blocks.smi` and `data/templates_extracted_5000.smi` in the working directory. Falls back to the embedded `DEFAULT_BUILDING_BLOCKS` / `default_rules()` defaults if not found (152 unique building blocks per `ChemEnv::bb_count()`, 21 handcrafted rules — verified 2026-08-29, after `heck_retro`'s removal (ring-fusion connectivity-collapse defect on internal alkenes fused to the same aromatic ring the leaving-group Br attaches to, confirmed by direct `apply_retro` reproduction on indene) dropped the count from 22, which itself followed `negishi_retro`'s and `grignard_addition_retro`'s removal (v0.36.0 rule-safety census: same ring-fused-atom-duplication defect as `aryl_amine_retro`/`buchwald_hartwig_retro`) dropping it from 24; a "509-BB / 20-rule" figure was previously documented here without verification).
+The server auto-detects `data/building_blocks.smi` and `data/templates_extracted_5000.smi` in the working directory. Falls back to the embedded `DEFAULT_BUILDING_BLOCKS` / `default_rules()` defaults if not found (152 unique building blocks per `ChemEnv::bb_count()`, 22 handcrafted rules, including the new graph-based `carbamate_cleavage` rule).
 
 ```bash
 cargo build --release
@@ -670,7 +675,7 @@ renkin/                          ← Cargo workspace root
 ├── scripts/
 │   ├── extract_templates.py         # rdchiral template extraction pipeline
 │   ├── run_benchmark_chunks.sh      # resumable chunked benchmark runner
-│   ├── train_reranker.py            # candidate reranker training/evaluation (dev tool, offline only — see docs/guides/reranker-candidate-pools.md)
+│   ├── train_reranker.py            # candidate reranker training/evaluation (dev tool, offline only)
 │   └── tests/                       # unittest suite for train_reranker.py
 ├── docs/                # MkDocs source → kent-tokyo.github.io/renkin/
 └── mkdocs.yml
@@ -695,7 +700,7 @@ see "Earlier milestones" below for older shipped work.
 - [x] Coverage mode (`--search-mode coverage`, [#101](https://github.com/kent-tokyo/renkin/issues/101), shipped v0.24.0) — opt-in Stage-1/Stage-2 template-count escalation, addressing the candidate-generation coverage gap below. Confirmed by a one-shot 500-target formal-TEST (`data/coverage_mode_formal_test/protocol_v2.md`): coverage +6.0pp, net gain +30, zero regressions, zero reranker failures, Stage-2 timeout rate 0.25% — all against pre-registered thresholds. See the Key Features table above for the shipped surface
 - [x] Reranker made actually usable: Python exposure (`find_routes()`'s `reranker_model_path`/`reranker_freq_table_path`) and batteries-included model distribution (`scripts/fetch_reranker_model.py`, SHA-256-verified fetch from the v0.22.0 GitHub Release's canonical assets) ([#101](https://github.com/kent-tokyo/renkin/issues/101), shipped v0.23.0) — v0.22.0 proved the reranker works; v0.23.0 is the usability/distribution unlock, not a new accuracy claim
 - [x] LightGBM candidate reranker, trained/gated offline and wired into route search ([#101](https://github.com/kent-tokyo/renkin/issues/101) Task 35, CLI shipped v0.22.0) — LambdaMART model trained on real USPTO-50k labels, passed its VAL screening gate (top1 +11.7pp, MRR +11.3pp, top10 +9.3pp, bootstrap-CI-confirmed) and a formal 4,903-target TEST evaluation against the frozen model exactly once (top1 +12.7pp, MRR +11.9pp, top10 +9.1pp — consistent magnitude with VAL, no overfitting signal), then wired into `find_routes` as an ordering-only rank bonus and confirmed with a paired 100-target route-search gate: `route_to_configured_stock` 16→20/100 (+4/-0). See the Key Features table above
-- [x] Formal 500-target RENKIN vs AiZynthFinder comparison ([#66](https://github.com/kent-tokyo/renkin/issues/66)) — under a fixed 500-target sample, shared 393-compound stock, and each tool's configured policy/budget, RENKIN Conservative's `route_to_shared_stock` outcome was 9.8 percentage points higher than AiZynthFinder's (73/500 vs 24/500, 95% CI [7.0, 12.8], exact McNemar p≈1.9e-11) — a statistically significant paired difference under this protocol, not a general search-capability superiority claim. Native-mode configurations (each tool's own stock) diverge in the opposite direction, dominated by unmatched conditions including a large stock-size gap. See the [comparison guide](docs/guides/open-source-retrosynthesis-comparison.md) for the full, deliberately scoped interpretation.
+- [x] Formal 500-target RENKIN vs AiZynthFinder comparison ([#66](https://github.com/kent-tokyo/renkin/issues/66)) — under a fixed 500-target sample, shared 393-compound stock, and each tool's configured policy/budget, RENKIN Conservative's `route_to_shared_stock` outcome was 9.8 percentage points higher than AiZynthFinder's (73/500 vs 24/500). This is a protocol-specific paired result, not a general search-capability superiority claim; native-mode configurations use unmatched stocks and are not directly comparable.
 - [x] Ring-context safety guard for extracted templates ([#72](https://github.com/kent-tokyo/renkin/issues/72)/[#242](https://github.com/kent-tokyo/renkin/pull/242)) — opt-in `--ring-context-policy`/`--ring-context-sidecar`, catches extracted templates silently misapplying a ring-opening/closing disconnection their training data never saw; default remains `disabled` (unchanged legacy behavior)
 - [x] `atom_economy` no longer silently clamped to 100% when a route's represented precursor set can't account for the target's full mass ([#79](https://github.com/kent-tokyo/renkin/issues/79)) — a new `atom_economy_status` field (`normal`/`above_expected_range`/`not_evaluable`) reports this explicitly instead
 
@@ -707,8 +712,16 @@ see "Earlier milestones" below for older shipped work.
 
 ### Next
 
-- [ ] Graph rule expansion — sulfonamide / carbamate / urea cleavage (one PR per family, each with benchmark delta)
+- [x] Graph rule expansion — sulfonamide and carbamate cleavage (one PR per family, with structural and atom-accounting gates; carbamate shipped v0.61.0)
+- [x] Urea cleavage — validated atom-balanced disconnection to isocyanate + amine; implemented locally as the next-version candidate (not published)
 - [ ] Stock-aware planning (price / hazard / availability re-ranking)
+  - [x] Deterministic policy-aware vendor-offer selection (price, lead time,
+    availability) for exact private-stock matches
+  - [x] Optional local hazard labels and blocked-hazard policy decisions
+  - [x] Route-level stock score and deterministic multi-route ranking metadata
+  - [x] Constraint DSL route-cost cap (`max_route_cost`) with explicit route-cost semantics
+  - [x] Exact canonical building-block exclusion (`avoid_building_blocks`) for private/constrained stock policies
+  - [x] Exact canonical building-block requirement (`require_building_blocks`) for house-stock policies
 
 <details>
 <summary>Earlier milestones</summary>

package/package.json

@@ -5,7 +5,7 @@
     "kent-tokyo <kent-tokyo@users.noreply.github.com>"
   ],
   "description": "Ultra-fast retrosynthesis engine for computer-aided synthesis planning (CASP) — pure Rust, WASM-ready, Python bindings via PyO3",
-  "version": "0.60.0",
+  "version": "1.0.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/renkin.d.ts

@@ -138,6 +138,16 @@ export function find_routes_v4(target: string, depth: number, max_routes: number
  */
 export function find_routes_v5(target: string, depth: number, max_routes: number, beam_width: number, avoid_elements: string, require_elements: string, spectator_bond_policy: string, element_accounting_policy: string, beam_diversity_policy: string, beam_diversity_slots: number): string;
 
+/**
+ * Same as [`find_routes_v5`], plus bounded candidate-level diagnostics.
+ * `candidate_trace_limit` is an explicit collection cap; `0` collects no
+ * records while still returning the aggregate `search_diagnostics` block.
+ * The diagnostics are read-only and do not affect route selection. A new
+ * export preserves the fail-loud compatibility behavior of the earlier
+ * versioned WASM functions.
+ */
+export function find_routes_v6(target: string, depth: number, max_routes: number, beam_width: number, avoid_elements: string, require_elements: string, spectator_bond_policy: string, element_accounting_policy: string, beam_diversity_policy: string, beam_diversity_slots: number, candidate_trace_limit: number): string;
+
 /**
  * Return the crate version string.
  */
@@ -155,6 +165,7 @@ export interface InitOutput {
     readonly find_routes_v3: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => [number, number];
     readonly find_routes_v4: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number, n: number) => [number, number];
     readonly find_routes_v5: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number, n: number, o: number, p: number) => [number, number];
+    readonly find_routes_v6: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number, n: number, o: number, p: number, q: number) => [number, number];
     readonly version: () => [number, number];
     readonly __wbindgen_externrefs: WebAssembly.Table;
     readonly __wbindgen_malloc: (a: number, b: number) => number;

package/renkin.js

@@ -328,6 +328,51 @@ export function find_routes_v5(target, depth, max_routes, beam_width, avoid_elem
     }
 }
 
+/**
+ * Same as [`find_routes_v5`], plus bounded candidate-level diagnostics.
+ * `candidate_trace_limit` is an explicit collection cap; `0` collects no
+ * records while still returning the aggregate `search_diagnostics` block.
+ * The diagnostics are read-only and do not affect route selection. A new
+ * export preserves the fail-loud compatibility behavior of the earlier
+ * versioned WASM functions.
+ * @param {string} target
+ * @param {number} depth
+ * @param {number} max_routes
+ * @param {number} beam_width
+ * @param {string} avoid_elements
+ * @param {string} require_elements
+ * @param {string} spectator_bond_policy
+ * @param {string} element_accounting_policy
+ * @param {string} beam_diversity_policy
+ * @param {number} beam_diversity_slots
+ * @param {number} candidate_trace_limit
+ * @returns {string}
+ */
+export function find_routes_v6(target, depth, max_routes, beam_width, avoid_elements, require_elements, spectator_bond_policy, element_accounting_policy, beam_diversity_policy, beam_diversity_slots, candidate_trace_limit) {
+    let deferred7_0;
+    let deferred7_1;
+    try {
+        const ptr0 = passStringToWasm0(target, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(avoid_elements, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ptr2 = passStringToWasm0(require_elements, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len2 = WASM_VECTOR_LEN;
+        const ptr3 = passStringToWasm0(spectator_bond_policy, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len3 = WASM_VECTOR_LEN;
+        const ptr4 = passStringToWasm0(element_accounting_policy, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len4 = WASM_VECTOR_LEN;
+        const ptr5 = passStringToWasm0(beam_diversity_policy, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len5 = WASM_VECTOR_LEN;
+        const ret = wasm.find_routes_v6(ptr0, len0, depth, max_routes, beam_width, ptr1, len1, ptr2, len2, ptr3, len3, ptr4, len4, ptr5, len5, beam_diversity_slots, candidate_trace_limit);
+        deferred7_0 = ret[0];
+        deferred7_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred7_0, deferred7_1, 1);
+    }
+}
+
 /**
  * Return the crate version string.
  * @returns {string}