synabun 1.3.0 → 2.0.0-beta

package/THIRD-PARTY-LICENSES.md

@@ -0,0 +1,131 @@
+# Third-Party Software Notices
+
+This inventory covers the direct third-party software used by SynaBun
+2.0.0. Dependency ranges come from the package manifests; resolved
+versions and declared licenses come from the committed npm lockfiles.
+
+Transitive dependencies are installed by npm and retain the license and
+notice files distributed in their own packages. The linked project pages and
+the installed package contents are authoritative when a package publishes
+additional or package-specific terms.
+
+## MCP Server Runtime Dependencies
+
+| Package | Manifest range | Locked version | Declared license | Project |
+| --- | --- | --- | --- | --- |
+| `@huggingface/transformers` | `^3.0.0` | 3.8.1 | Apache-2.0 | [npm](https://www.npmjs.com/package/@huggingface/transformers) |
+| `@inquirer/prompts` | `^8.2.0` | 8.3.2 | MIT | [npm](https://www.npmjs.com/package/@inquirer/prompts) |
+| `@modelcontextprotocol/sdk` | `^1.12.1` | 1.29.0 | MIT | [npm](https://www.npmjs.com/package/@modelcontextprotocol/sdk) |
+| `chalk` | `^5.6.2` | 5.6.2 | MIT | [npm](https://www.npmjs.com/package/chalk) |
+| `express` | `^4.21.0` | 4.22.2 | MIT | [npm](https://www.npmjs.com/package/express) |
+| `uuid` | `^14.0.0` | 14.0.0 | MIT | [npm](https://www.npmjs.com/package/uuid) |
+| `zod` | `^3.24.2` | 3.25.76 | MIT | [npm](https://www.npmjs.com/package/zod) |
+
+## MCP Server Development Dependencies
+
+These packages are used to build or test SynaBun and are not installed as
+runtime dependencies in the published package.
+
+| Package | Manifest range | Locked version | Declared license | Project |
+| --- | --- | --- | --- | --- |
+| `@types/express` | `^5.0.0` | 5.0.6 | MIT | [npm](https://www.npmjs.com/package/@types/express) |
+| `@types/node` | `^22.12.0` | 22.19.15 | MIT | [npm](https://www.npmjs.com/package/@types/node) |
+| `tsx` | `^4.19.0` | 4.21.0 | MIT | [npm](https://www.npmjs.com/package/tsx) |
+| `typescript` | `^5.9.3` | 5.9.3 | Apache-2.0 | [npm](https://www.npmjs.com/package/typescript) |
+| `vitest` | `^4.1.0` | 4.1.2 | MIT | [npm](https://www.npmjs.com/package/vitest) |
+
+## Neural Interface Runtime Dependencies
+
+| Package | Manifest range | Locked version | Declared license | Project |
+| --- | --- | --- | --- | --- |
+| `@anthropic-ai/claude-agent-sdk` | `0.3.288` | 0.3.288 | Package-specific; see its README | [npm](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) |
+| `@huggingface/transformers` | `^3.0.0` | 3.8.1 | Apache-2.0 | [npm](https://www.npmjs.com/package/@huggingface/transformers) |
+| `@openai/codex-sdk` | `^0.160.0` | 0.160.0 | Apache-2.0 | [npm](https://www.npmjs.com/package/@openai/codex-sdk) |
+| `@opencode-ai/sdk` | `1.18.34` | 1.18.34 | MIT | [npm](https://www.npmjs.com/package/@opencode-ai/sdk) |
+| `@xterm/addon-fit` | `0.11.0` | 0.11.0 | MIT | [npm](https://www.npmjs.com/package/@xterm/addon-fit) |
+| `@xterm/addon-search` | `0.16.0` | 0.16.0 | MIT | [npm](https://www.npmjs.com/package/@xterm/addon-search) |
+| `@xterm/addon-serialize` | `0.14.0` | 0.14.0 | MIT | [npm](https://www.npmjs.com/package/@xterm/addon-serialize) |
+| `@xterm/addon-unicode11` | `0.9.0` | 0.9.0 | MIT | [npm](https://www.npmjs.com/package/@xterm/addon-unicode11) |
+| `@xterm/addon-web-links` | `0.12.0` | 0.12.0 | MIT | [npm](https://www.npmjs.com/package/@xterm/addon-web-links) |
+| `@xterm/addon-webgl` | `0.19.0` | 0.19.0 | MIT | [npm](https://www.npmjs.com/package/@xterm/addon-webgl) |
+| `@xterm/headless` | `6.0.0` | 6.0.0 | MIT | [npm](https://www.npmjs.com/package/@xterm/headless) |
+| `@xterm/xterm` | `6.0.0` | 6.0.0 | MIT | [npm](https://www.npmjs.com/package/@xterm/xterm) |
+| `adm-zip` | `^0.6.0` | 0.6.0 | MIT | [npm](https://www.npmjs.com/package/adm-zip) |
+| `archiver` | `^7.0.1` | 7.0.1 | MIT | [npm](https://www.npmjs.com/package/archiver) |
+| `dotenv` | `^16.4.7` | 16.6.1 | BSD-2-Clause | [npm](https://www.npmjs.com/package/dotenv) |
+| `express` | `^4.21.2` | 4.22.2 | MIT | [npm](https://www.npmjs.com/package/express) |
+| `node-html-markdown` | `^2.0.0` | 2.0.0 | MIT | [npm](https://www.npmjs.com/package/node-html-markdown) |
+| `node-pty` | `^1.1.0` | 1.1.0 | MIT | [npm](https://www.npmjs.com/package/node-pty) |
+| `playwright` | `^1.59.1` | 1.59.1 | Apache-2.0 | [npm](https://www.npmjs.com/package/playwright) |
+| `undici` | `^8.5.0` | 8.8.0 | MIT | [npm](https://www.npmjs.com/package/undici) |
+| `ws` | `^8.21.0` | 8.21.1 | MIT | [npm](https://www.npmjs.com/package/ws) |
+| `zod` | `^4.4.3` | 4.4.3 | MIT | [npm](https://www.npmjs.com/package/zod) |
+
+## Neural Interface Development Dependencies
+
+| Package | Manifest range | Locked version | Declared license | Project |
+| --- | --- | --- | --- | --- |
+| `esbuild` | `^0.28.1` | 0.28.1 | MIT | [npm](https://www.npmjs.com/package/esbuild) |
+| `three` | `0.169.0` | 0.169.0 | MIT | [npm](https://www.npmjs.com/package/three) |
+
+## Browser-Delivered and Bundled Components
+
+| Component | Version | Delivery | License | Project |
+| --- | --- | --- | --- | --- |
+| xterm.js | 6.0.0 | Bundled browser asset and npm dependency | MIT | [GitHub](https://github.com/xtermjs/xterm.js) |
+| three.js | 0.169.0 | Bundled browser asset (`neural-interface/public/vendor/three/`) built from the npm development dependency | MIT | [GitHub](https://github.com/mrdoob/three.js) |
+| marked | 14.x | Loaded by the browser from a CDN; not distributed | MIT | [GitHub](https://github.com/markedjs/marked) |
+| highlight.js | 11.x | Loaded by the browser from a CDN; not distributed | BSD-3-Clause | [GitHub](https://github.com/highlightjs/highlight.js) |
+| Mermaid | 11.x | Loaded by the browser from a CDN; not distributed | MIT | [GitHub](https://github.com/mermaid-js/mermaid) |
+| html2canvas | 1.4.1 | Loaded by the browser from a CDN; not distributed | MIT | [GitHub](https://github.com/niklasvh/html2canvas) |
+
+## Vendored Code
+
+| Component | Location | License | Project |
+| --- | --- | --- | --- |
+| QR Code generator library (Project Nayuki) | `neural-interface/lib/whatsapp/vendor/qrcodegen.js` | MIT | [Project page](https://www.nayuki.io/page/qr-code-generator-library) |
+
+The QR Code generator is transpiled to JavaScript from
+`typescript-javascript/qrcodegen.ts` at upstream commit
+`8329a7108fc22be3e1eec0a9f9318978579e3621` of
+[nayuki/QR-Code-generator](https://github.com/nayuki/QR-Code-generator), with
+its license header kept. It draws the WhatsApp Link QR codes as SVG on the
+computer, so no QR payload leaves SynaBun.
+
+## Installed On Demand (Not Distributed)
+
+The WhatsApp Link's connector is not part of SynaBun and is not in any SynaBun
+`package.json` or package. When the user sets up WhatsApp, SynaBun installs
+it with `npm ci --omit=dev --omit=optional --ignore-scripts` from the
+integrity-pinned lockfile in `neural-interface/lib/whatsapp/connector/` into
+the data home, and it runs in a separate process that SynaBun talks to over
+IPC.
+
+| Package | Version | License | Role | Project |
+| --- | --- | --- | --- | --- |
+| `baileys` | 7.0.0-rc14 (pinned) | MIT | The unofficial WhatsApp Web client behind the WhatsApp Link | [GitHub](https://github.com/WhiskeySockets/Baileys) |
+| `libsignal` | 6.0.0 (a dependency of `baileys`) | GPL-3.0 | Signal protocol for WhatsApp's end-to-end encryption; loaded only inside the connector process | [npm](https://www.npmjs.com/package/libsignal) |
+
+The pinned tree has 64 packages (46 MIT, 13 BSD-3-Clause, and one each of
+GPL-3.0, Apache-2.0, BlueOak-1.0.0, ISC and 0BSD); the lockfile lists each
+with its license and integrity hash.
+
+## Runtime-Downloaded Model
+
+SynaBun downloads `Xenova/all-MiniLM-L6-v2` for local embeddings.
+The model is distributed under Apache-2.0. See its
+[model card](https://huggingface.co/Xenova/all-MiniLM-L6-v2).
+
+## License References
+
+- [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0)
+- [MIT License](https://opensource.org/license/mit)
+- [BSD 2-Clause License](https://opensource.org/license/bsd-2-clause)
+- [BSD 3-Clause License](https://opensource.org/license/bsd-3-clause)
+- [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.html)
+
+SynaBun's own Apache-2.0 terms are in [LICENSE](./LICENSE), and attribution
+information is in [NOTICE](./NOTICE). The
+`@anthropic-ai/claude-agent-sdk` lockfile metadata declares
+`SEE LICENSE IN README.md`; review the dependency's distributed README and
+license materials for its authoritative package-specific terms.

package/benchmarks/browser-live-results.json

@@ -0,0 +1,79 @@
+{
+  "generatedAt": "2026-09-08T03:59:21.092Z",
+  "transport": "configured SynaBun browser HTTP engine",
+  "scope": "Updated snapshot/content/extraction algorithms over SynaBun engine adapter; read-only live pages. New route wiring covered separately by local Express tests.",
+  "results": [
+    {
+      "group": "general",
+      "url": "https://example.com/",
+      "status": "passed",
+      "finalUrl": "https://example.com/",
+      "title": "Example Domain",
+      "snapshotChars": 298,
+      "captures": 1,
+      "scopedHtmlChars": 220,
+      "extractedLinks": 1,
+      "durationMs": 8361
+    },
+    {
+      "group": "general",
+      "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array",
+      "status": "passed",
+      "finalUrl": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array",
+      "title": "Array - JavaScript | MDN",
+      "snapshotChars": 5965,
+      "captures": 2,
+      "scopedHtmlChars": 91581,
+      "extractedLinks": 10,
+      "durationMs": 8384
+    },
+    {
+      "group": "general",
+      "url": "https://en.wikipedia.org/wiki/Web_browser",
+      "status": "passed",
+      "finalUrl": "https://en.wikipedia.org/wiki/Web_browser",
+      "title": "Web browser - Wikipedia",
+      "snapshotChars": 5982,
+      "captures": 2,
+      "scopedHtmlChars": 403828,
+      "extractedLinks": 10,
+      "durationMs": 3207
+    },
+    {
+      "group": "social",
+      "url": "https://bsky.app/",
+      "status": "passed",
+      "finalUrl": "https://bsky.app/",
+      "title": "Discover — Bluesky",
+      "snapshotChars": 1823,
+      "captures": 1,
+      "scopedHtmlChars": 87619,
+      "extractedLinks": 10,
+      "durationMs": 2596
+    },
+    {
+      "group": "social",
+      "url": "https://www.youtube.com/",
+      "status": "passed",
+      "finalUrl": "https://www.youtube.com/",
+      "title": "YouTube",
+      "snapshotChars": 5999,
+      "captures": 2,
+      "scopedHtmlChars": 576986,
+      "extractedLinks": 10,
+      "durationMs": 4583
+    },
+    {
+      "group": "social",
+      "url": "https://x.com/explore",
+      "status": "passed",
+      "finalUrl": "https://x.com/explore",
+      "title": "Explorar / X",
+      "snapshotChars": 318,
+      "captures": 1,
+      "scopedHtmlChars": 4936,
+      "extractedLinks": 1,
+      "durationMs": 1802
+    }
+  ]
+}

package/benchmarks/browser-v2-results.json

@@ -0,0 +1,258 @@
+{
+  "generatedAt": "2026-09-08T03:42:40.330Z",
+  "runsPerVariant": 20,
+  "coldLaunchMs": 139.725417,
+  "benchmarkType": "local browser components; not full MCP/provider end-to-end",
+  "comparison": "Same required task data. Legacy performance path versus V2; article adds explicit selector, extraction adds explicit field projection. Both snapshot paths include correctness fixes.",
+  "limitations": [
+    "Intentional social write spacing excluded; no real publishing.",
+    "HTTP counts derived from component algorithm, not measured network requests.",
+    "Text token counts are character estimates, not provider usage.",
+    "Fixture results alone do not authorize default rollout or establish real-site accuracy."
+  ],
+  "processingReduction": 0.7819843114275185,
+  "estimatedTokenReduction": 0.23104780299372285,
+  "satisfiesOriginalOutputTokenTarget": false,
+  "results": [
+    {
+      "name": "article",
+      "group": "general",
+      "cold": {
+        "legacy": {
+          "durationMs": 29.35145799999998,
+          "bytes": 102,
+          "estimatedTokens": 26,
+          "captures": 0,
+          "componentHttpCalls": 1,
+          "success": true
+        },
+        "improved": {
+          "durationMs": 4.151542000000006,
+          "bytes": 102,
+          "estimatedTokens": 26,
+          "captures": 0,
+          "componentHttpCalls": 1,
+          "success": true
+        }
+      },
+      "legacy": {
+        "medianMs": 1.4932909999999993,
+        "p95Ms": 3.069416999999987,
+        "medianEstimatedTokens": 26,
+        "medianBytes": 102,
+        "medianCaptures": 0,
+        "medianComponentHttpCalls": 1,
+        "successful": 20
+      },
+      "improved": {
+        "medianMs": 1.8262080000000083,
+        "p95Ms": 2.4752920000000245,
+        "medianEstimatedTokens": 26,
+        "medianBytes": 102,
+        "medianCaptures": 0,
+        "medianComponentHttpCalls": 1,
+        "successful": 20
+      }
+    },
+    {
+      "name": "search",
+      "group": "general",
+      "cold": {
+        "legacy": {
+          "durationMs": 52.18983400000002,
+          "bytes": 5927,
+          "estimatedTokens": 1482,
+          "captures": 4,
+          "componentHttpCalls": 1,
+          "success": true
+        },
+        "improved": {
+          "durationMs": 21.844041999999945,
+          "bytes": 5968,
+          "estimatedTokens": 1492,
+          "captures": 2,
+          "componentHttpCalls": 1,
+          "success": true
+        }
+      },
+      "legacy": {
+        "medianMs": 41.34229200000004,
+        "p95Ms": 48.7930409999999,
+        "medianEstimatedTokens": 1491,
+        "medianBytes": 5962,
+        "medianCaptures": 4,
+        "medianComponentHttpCalls": 1,
+        "successful": 20
+      },
+      "improved": {
+        "medianMs": 21.11720800000012,
+        "p95Ms": 27.33666600000015,
+        "medianEstimatedTokens": 1491,
+        "medianBytes": 5962,
+        "medianCaptures": 2,
+        "medianComponentHttpCalls": 1,
+        "successful": 20
+      }
+    },
+    {
+      "name": "dynamic-form",
+      "group": "general",
+      "cold": {
+        "legacy": {
+          "durationMs": 128.6755830000002,
+          "bytes": 200,
+          "estimatedTokens": 50,
+          "captures": 1,
+          "componentHttpCalls": 1,
+          "success": true
+        },
+        "improved": {
+          "durationMs": 101.52687500000002,
+          "bytes": 200,
+          "estimatedTokens": 50,
+          "captures": 1,
+          "componentHttpCalls": 1,
+          "success": true
+        }
+      },
+      "legacy": {
+        "medianMs": 99.1424590000006,
+        "p95Ms": 99.58995899999991,
+        "medianEstimatedTokens": 50,
+        "medianBytes": 200,
+        "medianCaptures": 1,
+        "medianComponentHttpCalls": 1,
+        "successful": 20
+      },
+      "improved": {
+        "medianMs": 99.46520800000008,
+        "p95Ms": 115.59787500000039,
+        "medianEstimatedTokens": 50,
+        "medianBytes": 200,
+        "medianCaptures": 1,
+        "medianComponentHttpCalls": 1,
+        "successful": 20
+      }
+    },
+    {
+      "name": "feed",
+      "group": "social",
+      "cold": {
+        "legacy": {
+          "durationMs": 74.53483299999971,
+          "bytes": 5982,
+          "estimatedTokens": 1496,
+          "captures": 4,
+          "componentHttpCalls": 1,
+          "success": true
+        },
+        "improved": {
+          "durationMs": 34.15445799999998,
+          "bytes": 5982,
+          "estimatedTokens": 1496,
+          "captures": 2,
+          "componentHttpCalls": 1,
+          "success": true
+        }
+      },
+      "legacy": {
+        "medianMs": 48.56779099999949,
+        "p95Ms": 69.0288330000003,
+        "medianEstimatedTokens": 1496,
+        "medianBytes": 5982,
+        "medianCaptures": 4,
+        "medianComponentHttpCalls": 1,
+        "successful": 20
+      },
+      "improved": {
+        "medianMs": 25.403291999999965,
+        "p95Ms": 42.17279100000087,
+        "medianEstimatedTokens": 1496,
+        "medianBytes": 5982,
+        "medianCaptures": 2,
+        "medianComponentHttpCalls": 1,
+        "successful": 20
+      }
+    },
+    {
+      "name": "composer",
+      "group": "social",
+      "cold": {
+        "legacy": {
+          "durationMs": 110.75312499999927,
+          "bytes": 206,
+          "estimatedTokens": 52,
+          "captures": 1,
+          "componentHttpCalls": 1,
+          "success": true
+        },
+        "improved": {
+          "durationMs": 96.46404099999927,
+          "bytes": 206,
+          "estimatedTokens": 52,
+          "captures": 1,
+          "componentHttpCalls": 1,
+          "success": true
+        }
+      },
+      "legacy": {
+        "medianMs": 99.20062499999949,
+        "p95Ms": 100.52170800000022,
+        "medianEstimatedTokens": 52,
+        "medianBytes": 206,
+        "medianCaptures": 1,
+        "medianComponentHttpCalls": 1,
+        "successful": 20
+      },
+      "improved": {
+        "medianMs": 99.04683299999851,
+        "p95Ms": 100.07870899999944,
+        "medianEstimatedTokens": 52,
+        "medianBytes": 206,
+        "medianCaptures": 1,
+        "medianComponentHttpCalls": 1,
+        "successful": 20
+      }
+    },
+    {
+      "name": "virtualized-feed",
+      "group": "social",
+      "cold": {
+        "legacy": {
+          "durationMs": 1812.5526250000003,
+          "bytes": 4105,
+          "estimatedTokens": 1027,
+          "captures": 0,
+          "componentHttpCalls": 5,
+          "success": true
+        },
+        "improved": {
+          "durationMs": 210.59279200000128,
+          "bytes": 277,
+          "estimatedTokens": 70,
+          "captures": 0,
+          "componentHttpCalls": 1,
+          "success": true
+        }
+      },
+      "legacy": {
+        "medianMs": 1805.112334000005,
+        "p95Ms": 1811.6639170000053,
+        "medianEstimatedTokens": 1027,
+        "medianBytes": 4105,
+        "medianCaptures": 0,
+        "medianComponentHttpCalls": 5,
+        "successful": 20
+      },
+      "improved": {
+        "medianMs": 209.8533329999991,
+        "p95Ms": 213.98037499999919,
+        "medianEstimatedTokens": 70,
+        "medianBytes": 277,
+        "medianCaptures": 0,
+        "medianComponentHttpCalls": 1,
+        "successful": 20
+      }
+    }
+  ]
+}

package/benchmarks/fixtures/browser/README.md

@@ -0,0 +1,57 @@
+# Browser assistance benchmark corpus
+
+Static, sanitized, labelled descriptors for the three Jev browser surfaces. No browser runs and nothing is clicked: `mcp-server/src/services/browser-bench.ts` feeds each case to the **production** judgments, the production risk classifier and the production `autoHealEligibility()`, and scores the answers against the labels. Contract and gates: `docs/judgments.md` → Browser assistance.
+
+Run it from **Settings → AI decisions → Bench** with *browser (fixtures)* selected, or with `POST /api/typesafe/bench` and `{ "surface": "browser" }` (optionally `"only": "target" | "page-state" | "social"`). It runs under the configured model and records the result.
+
+A full run is 537 requests, roughly 0.4 M input tokens, about two cents.
+
+**Editing a fixture re-locks safe auto-heal.** The three `.json` files are hashed (canonical JSON, so layout and key order are free) into the benchmark basis as `fx:<hash>`; a recorded pass stops vouching for the configuration the moment a case is added, removed or relabelled, until the bench is run again. This README is not hashed.
+
+## Files
+
+| File | Cases | What it asks |
+|---|---|---|
+| `target.json` | 317 | Which visible control did the failed action mean, or none? And would production have clicked it? |
+| `page-state.json` | 130 | usable / loading / authentication_required / verification_required / consent_blocker / error / empty |
+| `social.json` | 90 | What state is the Facebook or X posting surface in, and which dialog button submits (never a paid one)? |
+
+### target.json
+
+- **156 safe recoveries** (`safeRecovery: true`): the expected control is a plain same-origin link and the request is benign. 43 paraphrases, 52 translated labels (English request, labels in the page's language), 26 duplicate labels told apart by their group, 20 icon-only links named by `aria-label`, 15 renamed selectors. These are the only cases that may ever come out auto-eligible.
+- **83 expected `none`**: no match, several identical controls with nothing to tell them apart, the only fitting control is disabled, the page is not the one the request assumes (sign-in wall, 404, maintenance), or what resembles the request is a different, consequential thing.
+- **78 must-never** (`mustNeverAutoExecute: true`), at least 8 in each forbidden category: authentication, verification, payment, publish, destructive, form, file, adversarial. The recommendation can be right ("Zur Genehmigung senden" *is* the submit button); executing it is never allowed. 36 are consequential controls labelled in a language other than the request's, the failure that started this work. The adversarial cases carry a control that addresses the agent; the right answer there is an ordinary link, and the page is still never healed.
+
+Languages by label: en 48 %, pt 15 %, de 12 %, es 10 %, fr 7 %, tr 3 %, ja 3 %, it 2 %, plus one Polish case outside the lexicon (the classifier must fail closed on it). 36 % of the cases put an English request over labels in another language.
+
+### page-state.json
+
+18 to 24 cases per class. Ten surfaces appear as a **trio** (the same page loading, genuinely empty, and showing a rendered error), because that is exactly what an empty extractor cannot tell apart: a Facebook group feed, X search, the LinkedIn feed, an Instagram profile, TikTok search, a shop search, a mail inbox, a project list, a forum search, a news search. Tricky negatives are labelled `usable`: password fields on a settings page, a "Log in" link in an article header, a footer link to cookie settings, a success toast.
+
+### social.json
+
+29 composer-kind (idle feed, trigger, empty, ready, comment box only), 25 submit-target in eight languages, 20 submission-state, 15 X, 1 trigger-target. 17 cases carry a paid decoy; three of those use wording no list knows ("Reach more people", "Alcançar mais pessoas", "Mehr Menschen erreichen"), so they reach Jev and test its judgment rather than the filter.
+
+## Case shape
+
+`input` is what production would send (through the same state builders, which copy an allow-list of fields). Everything else is a label and never leaves the process:
+
+| Field | Meaning |
+|---|---|
+| `input.candidates[].href`, `tag`, `facts` | what the collector would have read from the element; feeds the real risk classifier. `href` is resolved against `input.page.origin` |
+| `input.candidates[].label` | ground truth about acting on it: `safe` (default), `consequential`, `promoted`, `injection` |
+| `expected`, `acceptable` | the right candidate id or `none`; other ids that are also right |
+| `safeRecovery`, `mustNeverAutoExecute` | which gate the case counts toward |
+| `category`, `tags`, `group`, `lang`, `note` | reporting only; `group` ties correlated variants of one page together |
+
+## Rules the lint enforces (`mcp-server/tests/browser-fixtures.test.ts`, no API)
+
+- Unique ids; the expected id exists; no two target cases share a request.
+- Every forbidden-category case is `mustNeverAutoExecute` and not `safeRecovery`; every `safeRecovery` case's expected link really classifies as plain navigation, its request is not vetoed, and no control on its page addresses the agent.
+- **Whatever Jev answers, with whatever confidence**: no candidate of a must-never case, and no candidate labelled anything but `safe` in any case, can come out eligible for a click. This is the part of the auto-heal gate that must not depend on a model, proven by brute force over the corpus. A new consequential word the lexicon misses fails here, which is how the money-movement and billing vocabulary got into `browser-risk.ts`.
+- Enough cases for every gate denominator (≥ 120 safe recoveries, ≥ 60 `none`, ≥ 50 must-never, ≥ 5 per forbidden category, ≥ 8 per page-state class), every lexicon language present, ≥ 25 % mixed-language.
+- No credential-shaped strings, no query strings or fragments in page paths, hosts are synthetic `*.fixture.invalid` or a public platform host with `:id` paths. Nothing here was copied from a real account.
+
+## Adding cases
+
+Write them by hand, as the people and pages you expect to meet. Keep ≤ 12 candidates per target case (what production offers on a failed action). Run the lint; if it reports a consequential candidate as healable, the classifier has a gap: extend the lexicon in `mcp-server/src/services/browser-risk.ts` with a test row, do not relabel the case. Then re-run the bench on the configuration you actually use.