renkin 0.33.0 → 0.35.0

package/README.md

@@ -21,7 +21,7 @@
 
 ---
 
-**Keep your planner. Audit every route.** Audit retrosynthesis routes from AiZynthFinder, Syntheseus, or RENKIN — locally, reproducibly, and without sending molecular structures anywhere.
+**Keep your planner. Audit every route.** Audit retrosynthesis routes from AiZynthFinder, Syntheseus, SynPlanner, or RENKIN — locally, reproducibly, and without sending molecular structures anywhere.
 
 [**Audit a route in your browser →**](https://kent-tokyo.github.io/renkin/playground/) · [**Python quick start ↓**](#audit-a-route) · [**Route planning engine ↓**](#quick-start)
 
@@ -29,7 +29,7 @@
 
 ## What is RENKIN?
 
-RENKIN Bridge is a tool-neutral **route auditor**: it checks structural integrity, stock coverage, and declared-reaction forward-replay for routes from **AiZynthFinder**, **Syntheseus**, or RENKIN's own planner — the identical `pass`/`fail`/`partial` pipeline regardless of which tool produced the route, entirely local and reproducible (every audit records a verifiable [`audit_manifest`](https://kent-tokyo.github.io/renkin/guides/audit-reproducibility-contract/)), structures never leaving your machine unless you explicitly ask.
+RENKIN Bridge is a tool-neutral **route auditor**: it checks structural integrity, stock coverage, and declared-reaction forward-replay for routes from **AiZynthFinder**, **Syntheseus**, **SynPlanner**, or RENKIN's own planner — the identical `pass`/`fail`/`partial` pipeline regardless of which tool produced the route, entirely local and reproducible (every audit records a verifiable [`audit_manifest`](https://kent-tokyo.github.io/renkin/guides/audit-reproducibility-contract/)), structures never leaving your machine unless you explicitly ask.
 
 RENKIN is also, in its own right, an open-source **retrosynthesis engine** for **computer-aided synthesis planning (CASP)** that automatically discovers chemical reaction routes from a target molecule back to cheap, commercially available starting materials.
 
@@ -85,9 +85,21 @@ report = json.loads(renkin.audit_route(route_json, format="syntheseus"))
 print(report["summary"])
 ```
 
+**SynPlanner**
+
+```python
+import json
+import renkin
+
+report = json.loads(
+    renkin.audit_route(open("routes.json").read(), format="synplanner")
+)
+print(report["summary"])
+```
+
 **In your browser** — no installation, no upload, no server: [**Try the Playground →**](https://kent-tokyo.github.io/renkin/playground/)
 
-Full walkthroughs with real output, end to end: [AiZynthFinder](https://kent-tokyo.github.io/renkin/guides/aizynthfinder-audit-demo/) · [Syntheseus](https://kent-tokyo.github.io/renkin/guides/syntheseus-audit-demo/).
+Full walkthroughs with real output, end to end: [AiZynthFinder](https://kent-tokyo.github.io/renkin/guides/aizynthfinder-audit-demo/) · [Syntheseus](https://kent-tokyo.github.io/renkin/guides/syntheseus-audit-demo/) · [SynPlanner](https://kent-tokyo.github.io/renkin/guides/synplanner-audit-demo/).
 
 ---
 
@@ -393,7 +405,7 @@ for the full acceptance criteria and licensing split.
 | **Ring-context safety guard** | `--ring-context-policy conservative --ring-context-sidecar <path>` — opt-in match-level filter that rejects an extracted template's ring-opening/closing disconnection when its historical training data never observed that bond as ring-forming/-breaking; default `disabled` (unchanged legacy behavior) — see [Issue #72](https://github.com/kent-tokyo/renkin/issues/72) |
 | **LightGBM candidate reranker** | `--reranker-model`/`--reranker-freq-table` (CLI) or `reranker_model_path`/`reranker_freq_table_path` (Python) — opt-in, ordering-only re-ranking via a frozen LightGBM model; never changes which candidates are generated, only their order, and reproduces legacy ordering byte-for-byte when off. Paired 100-target route-search gate: `route_to_configured_stock` 16→20 (+4/-0). `python3 scripts/fetch_reranker_model.py` fetches the frozen model (SHA-256-verified, not bundled in any package — see [Roadmap](#roadmap)) |
 | **Coverage mode** (opt-in) | `--search-mode coverage --coverage-templates <path>` (CLI) or `search_mode="coverage"`, `coverage_templates_path=...` (Python) — if the default template set finds no route, automatically escalates to a larger, separately loaded template set, cooperatively cancellable via `--coverage-timeout-secs`. Standard-mode output is byte-for-byte unchanged when not used. `python3 scripts/fetch_coverage_templates.py` fetches the frozen 2,000-template Stage-2 set (SHA-256-verified, not bundled in any package, same reasoning as the reranker model — see [Roadmap](#roadmap)) |
-| **RENKIN Bridge / `audit-route`** | `renkin audit-route route.json [--format auto\|renkin\|aizynthfinder\|syntheseus] [--stock stock.smi] [--output human\|json]` — tool-neutral route audit: structural integrity, stock, and declared-reaction forward-replay validation, each reported independently as `pass`/`fail`/`not_evaluable`, rolled up into a route-level `pass`/`fail`/`partial` verdict. Reads RENKIN-native route JSON (v0.25.0), real AiZynthFinder route JSON — single-target and gzip-compressed batch output, verified against AiZynthFinder 4.3.2, 4.4.0, and 4.4.1 specifically, not claimed for every version (v0.26.0, version matrix widened v0.32.0) — and Syntheseus routes via the optional `renkin.syntheseus_exporter`'s `syntheseus-route-v1` interchange schema, since Syntheseus itself has no native route export (v0.30.0); `--format auto` detects the input shape and hard-errors rather than guessing on anything ambiguous. [AiZynthFinder walkthrough →](https://kent-tokyo.github.io/renkin/guides/aizynthfinder-audit-demo/) · [Syntheseus walkthrough →](https://kent-tokyo.github.io/renkin/guides/syntheseus-audit-demo/) |
+| **RENKIN Bridge / `audit-route`** | `renkin audit-route route.json [--format auto\|renkin\|aizynthfinder\|syntheseus\|synplanner] [--stock stock.smi] [--output human\|json]` — tool-neutral route audit: structural integrity, stock, and declared-reaction forward-replay validation, each reported independently as `pass`/`fail`/`not_evaluable`, rolled up into a route-level `pass`/`fail`/`partial` verdict. Reads RENKIN-native route JSON (v0.25.0), real AiZynthFinder route JSON — single-target and gzip-compressed batch output, verified against AiZynthFinder 4.3.2, 4.4.0, and 4.4.1 specifically, not claimed for every version (v0.26.0, version matrix widened v0.32.0) — Syntheseus routes via the optional `renkin.syntheseus_exporter`'s `syntheseus-route-v1` interchange schema, since Syntheseus itself has no native route export (v0.30.0) — and real SynPlanner 1.6.0 `write_routes_json` exports directly, no exporter package needed (v0.34.0); `--format auto` detects the input shape and hard-errors rather than guessing on anything ambiguous. [AiZynthFinder walkthrough →](https://kent-tokyo.github.io/renkin/guides/aizynthfinder-audit-demo/) · [Syntheseus walkthrough →](https://kent-tokyo.github.io/renkin/guides/syntheseus-audit-demo/) · [SynPlanner walkthrough →](https://kent-tokyo.github.io/renkin/guides/synplanner-audit-demo/) |
 | **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` |
@@ -551,7 +563,7 @@ The JSON output includes `avg_nodes_expanded`, `avg_confidence`, `avg_convergenc
 | `plan_with_constraints` | Constraint-DSL planning (element filters, step limits, confidence thresholds) |
 | `estimate_diversity` | Route diversity and coverage metrics |
 
-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()`, 27 handcrafted rules — verified 2026-08-22, after `aryl_amine_retro`'s removal (issue #77) dropped the count from 28; 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()`, 26 handcrafted rules — verified 2026-08-24, after `buchwald_hartwig_retro`'s removal (issue #77: same ring-fused-nitrogen atom-loss defect as `aryl_amine_retro`, plus a corrupted surviving fragment) dropped the count from 27; a "509-BB / 20-rule" figure was previously documented here without verification).
 
 ```bash
 cargo build --release
@@ -669,6 +681,7 @@ see "Earlier milestones" below for older shipped work.
 
 ### Recently shipped
 
+- [x] **SynPlanner Bridge** (`--format synplanner`, shipped v0.34.0) — *Keep SynPlanner. Audit its routes with RENKIN.* A fourth route adapter, and the first whose native export carries real, forward-replayable atom mapping: `renkin audit-route --format synplanner` (also auto-detected) reads real SynPlanner 1.6.0 `write_routes_json` exports directly, no exporter package needed. Confirmed against real SynPlanner output twice — hand-constructed reactions through SynPlanner's own exporter, and a real CPU-only MCTS-searched planning run through the real `synplan planning` CLI end to end — every one of 317 real reaction nodes across a 167-route real search carries a structurally valid atom map, and real routes reach a genuine `pass` verdict, not just `not_evaluable`. New 4-way (RENKIN-native/AiZynthFinder/Syntheseus/SynPlanner) structural and policy-verdict parity tests. The [browser playground](https://kent-tokyo.github.io/renkin/playground/)'s Audit tab gained SynPlanner as a fourth format option, with a one-click real-MCTS-output example. [5-minute walkthrough with real output →](https://kent-tokyo.github.io/renkin/guides/synplanner-audit-demo/)
 - [x] **Syntheseus Bridge** (`--format syntheseus`, shipped v0.30.0) — *Syntheseus has no route export. RENKIN built one — and audits it exactly like every other adapter.* A third route adapter alongside RENKIN-native and AiZynthFinder: the optional `renkin.syntheseus_exporter` (`pip install renkin[syntheseus]`) turns a real Syntheseus `SynthesisGraph` into the `syntheseus-route-v1` interchange schema, which `renkin audit-route --format syntheseus` (also auto-detected) consumes through the identical audit pipeline every adapter shares. Forward validation honestly reports `not_evaluable` for every real Syntheseus route today — `reaction_smiles` carries no atom mapping, never faked into a pass. The [browser playground](https://kent-tokyo.github.io/renkin/playground/)'s Audit tab gained Syntheseus as a third format option. [5-minute walkthrough with real output →](https://kent-tokyo.github.io/renkin/guides/syntheseus-audit-demo/)
 - [x] **Audit Policy Profiles** (`--policy informational|standard|strict`, shipped v0.29.0) — *One set of findings. Three ways to derive the verdict.* Audit the same route under `informational`, `standard`, or `strict` policy without ever hiding or changing the underlying findings — policy only changes how the overall pass/fail/partial verdict is derived from findings already collected, recorded in `audit_manifest.policy`. Consistent across every surface: `renkin audit-route --policy`, the Rust API, the first Python binding for route auditing (`renkin.audit_route()`), and a new WASM `audit_route_v2()` (the existing `audit_route()` stays as a `standard`-policy wrapper). The [browser playground](https://kent-tokyo.github.io/renkin/playground/)'s Audit tab gained a policy selector.
 - [x] **Audit Playground** (`[ Audit a Route ]` tab, shipped v0.28.0) — *Audit a route in your browser — the same pipeline, the same verdict, zero network calls.* The [browser playground](https://kent-tokyo.github.io/renkin/playground/) now audits a RENKIN or AiZynthFinder route export (single-route or Pandas batch) and an optional stock list entirely client-side, via a new `audit_route` WASM export that calls the identical report-building pipeline `renkin audit-route` uses — the same pass/fail/partial verdict either way, not a separately-maintained copy. Paste or upload, run off the main thread, download the JSON report.

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.33.0",
+  "version": "0.35.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/renkin.d.ts

@@ -84,6 +84,25 @@ export function find_routes(target: string, depth: number, max_routes: number, b
  */
 export function find_routes_v2(target: string, depth: number, max_routes: number, beam_width: number, avoid_elements: string, require_elements: string): string;
 
+/**
+ * Same as [`find_routes_v2`], plus `spectator_bond_policy`
+ * (`docs/design/spectator-bond-fail-closed-gating-v0.md`): `"off"`
+ * (default) | `"diagnostics_only"` | `"gated"`, same vocabulary as the
+ * CLI's `--spectator-bond-policy` flag and the Python binding's
+ * `spectator_bond_policy` kwarg. `"gated"` can change which candidates
+ * (and therefore which `routes`) come back -- v1 scope only: rules with
+ * no `#` in their SMIRKS, others stay diagnostics-only regardless of this
+ * setting. A distinct function name rather than a 5th parameter on
+ * `find_routes_v2`, matching that function's own stated reasoning (a
+ * caller on an older build gets a real "no such export" `TypeError`
+ * instead of a silently-ignored argument). Findings/gated-out records
+ * themselves aren't surfaced in this output yet -- WASM has no
+ * `search_diagnostics`-equivalent block at all today, for any
+ * `CrowdOutDiagnostics` field, not just this one; only the policy control
+ * itself (and its effect on `routes`) is in scope here.
+ */
+export function find_routes_v3(target: string, depth: number, max_routes: number, beam_width: number, avoid_elements: string, require_elements: string, spectator_bond_policy: string): string;
+
 /**
  * Return the crate version string.
  */
@@ -98,6 +117,7 @@ export interface InitOutput {
     readonly capabilities: () => [number, number];
     readonly find_routes: (a: number, b: number, c: number, d: number, e: number) => [number, number];
     readonly find_routes_v2: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => [number, number];
+    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 version: () => [number, number];
     readonly __wbindgen_externrefs: WebAssembly.Table;
     readonly __wbindgen_malloc: (a: number, b: number) => number;

package/renkin.js

@@ -182,6 +182,52 @@ export function find_routes_v2(target, depth, max_routes, beam_width, avoid_elem
     }
 }
 
+/**
+ * Same as [`find_routes_v2`], plus `spectator_bond_policy`
+ * (`docs/design/spectator-bond-fail-closed-gating-v0.md`): `"off"`
+ * (default) | `"diagnostics_only"` | `"gated"`, same vocabulary as the
+ * CLI's `--spectator-bond-policy` flag and the Python binding's
+ * `spectator_bond_policy` kwarg. `"gated"` can change which candidates
+ * (and therefore which `routes`) come back -- v1 scope only: rules with
+ * no `#` in their SMIRKS, others stay diagnostics-only regardless of this
+ * setting. A distinct function name rather than a 5th parameter on
+ * `find_routes_v2`, matching that function's own stated reasoning (a
+ * caller on an older build gets a real "no such export" `TypeError`
+ * instead of a silently-ignored argument). Findings/gated-out records
+ * themselves aren't surfaced in this output yet -- WASM has no
+ * `search_diagnostics`-equivalent block at all today, for any
+ * `CrowdOutDiagnostics` field, not just this one; only the policy control
+ * itself (and its effect on `routes`) is in scope here.
+ * @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
+ * @returns {string}
+ */
+export function find_routes_v3(target, depth, max_routes, beam_width, avoid_elements, require_elements, spectator_bond_policy) {
+    let deferred5_0;
+    let deferred5_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 ret = wasm.find_routes_v3(ptr0, len0, depth, max_routes, beam_width, ptr1, len1, ptr2, len2, ptr3, len3);
+        deferred5_0 = ret[0];
+        deferred5_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred5_0, deferred5_1, 1);
+    }
+}
+
 /**
  * Return the crate version string.
  * @returns {string}