Publish Vons source preview and reviewed research PDFs

.gitattributes

@@ -1,35 +1,12 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+* text=auto
+*.py text eol=lf
+*.ts text eol=lf
+*.mjs text eol=lf
+*.md text eol=lf
+*.json text eol=lf
+*.yml text eol=lf
+*.cff text eol=lf
+*.pdf binary
+*.png binary
+docs/publications/vons-paper-v1.0.pdf filter=lfs diff=lfs merge=lfs -text
+docs/publications/vons-tech-report-v1.0.1.pdf filter=lfs diff=lfs merge=lfs -text

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,31 @@
+name: Bug report
+description: Report unexpected behavior with a minimal safe reproduction.
+title: "[Bug] "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        For security issues, contact oswarld@inlevel9.com privately with a brief,
+        nonsensitive description first. Do not post secrets or restricted inputs.
+        English and Korean reports are welcome.
+  - type: textarea
+    id: environment
+    attributes:
+      label: Version and environment
+      description: Source revision or release manifest, OS, runtime version and optional model/provider identity.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: Exact command and preferably synthetic input; remove personal information and credentials.
+    validations:
+      required: true
+  - type: textarea
+    id: behavior
+    attributes:
+      label: Expected and actual behavior
+      description: Include safe error output, frequency and any workaround.
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/experience.yml

@@ -0,0 +1,55 @@
+name: Experience report
+description: Share what worked, failed or remained unclear when trying Vons.
+title: "[Experience] "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Positive and negative experiences are welcome, in English or Korean.
+        This is a public report once the repository is public. Use synthetic or
+        redacted examples. Do not upload secrets, private prompts, customer traces,
+        restricted data or model weights. A report is not benchmark validation.
+  - type: dropdown
+    id: path
+    attributes:
+      label: What did you try?
+      options:
+        - Documentation or installation
+        - Deterministic contract / KASI adapter
+        - Synthetic data walkthrough
+        - Model inference with separately supplied assets
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version or source identity
+      description: Commit, release manifest digest or explicitly unknown; include asset digest for inference.
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Scenario and environment
+      description: Your goal, OS, Python or Node version, device, runtime and provider. Omit personal details.
+    validations:
+      required: true
+  - type: textarea
+    id: outcome
+    attributes:
+      label: Expected and observed behavior
+      description: Include the command or steps, what helped, what failed and limitations.
+    validations:
+      required: true
+  - type: textarea
+    id: counts
+    attributes:
+      label: Counts and optional safe evidence
+      description: Attempted / successful / abstained / failed with definitions; explain overlaps. Use unavailable where unmeasured. Link only reviewed evidence.
+  - type: checkboxes
+    id: privacy
+    attributes:
+      label: Public content check
+      options:
+        - label: I reviewed this report for secrets, personal information and restricted material, and may share its contents.
+          required: true

.github/ISSUE_TEMPLATE/reproduction.yml

@@ -0,0 +1,50 @@
+name: Reproduction report
+description: Report a scoped attempt to reproduce a documented behavior or result.
+title: "[Reproduction] "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        An unsuccessful reproduction is useful. Keep raw records locally and
+        publish only permitted, reviewed aggregates or synthetic examples.
+        English and Korean reports are welcome. Missing evidence is unavailable.
+  - type: textarea
+    id: claim
+    attributes:
+      label: Claim and source
+      description: Link the exact document/version and state the claim's scope and expected result.
+    validations:
+      required: true
+  - type: textarea
+    id: setup
+    attributes:
+      label: Versions, inputs and environment
+      description: Source revision or manifest, model/tokenizer hashes if used, permitted input provenance, split, seed, OS/device/runtime/provider. Do not attach restricted inputs.
+    validations:
+      required: true
+  - type: textarea
+    id: procedure
+    attributes:
+      label: Commands and measurement procedure
+      description: Include warm-up, repetitions, timing or memory scope and analysis choices where applicable.
+    validations:
+      required: true
+  - type: textarea
+    id: results
+    attributes:
+      label: Observed results and denominators
+      description: Attempts, successes, abstentions, failures and unavailable values; include definitions, mismatches and limitations. Separate targets from measurements.
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Optional permitted evidence
+      description: Safe aggregate report or synthetic fixture with hashes; state what cannot be shared or independently checked.
+  - type: checkboxes
+    id: privacy
+    attributes:
+      label: Public content check
+      options:
+        - label: I reviewed the report and attachments for secrets, personal information and restricted material, and may share them.
+          required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,16 @@
+## Problem and change
+
+Describe the behavior before and after this change, and link the related issue.
+
+## Verification
+
+List commands run and their results. State skips, unavailable evidence and known
+limitations. Separate measured values from proposed targets.
+
+## Review notes
+
+- Explain any public contract, dependency, data or license implications.
+- Identify third-party material and its provenance when applicable.
+- Keep raw restricted data, model weights, secrets and private prompts out.
+- Update the release allowlist for reviewed new public files.
+- Preserve the separation between model decisions and host execution/consent.

.github/workflows/checks.yml

@@ -0,0 +1,61 @@
+name: Source checks
+
+on:
+  push:
+    paths:
+      - '.github/workflows/checks.yml'
+      - 'vons/**'
+      - 'tools/**'
+      - 'tests/**'
+      - 'configs/**'
+      - 'sdk/**'
+      - 'pyproject.toml'
+      - '.gitignore'
+  pull_request:
+    paths:
+      - '.github/workflows/checks.yml'
+      - 'vons/**'
+      - 'tools/**'
+      - 'tests/**'
+      - 'configs/**'
+      - 'sdk/**'
+      - 'pyproject.toml'
+      - '.gitignore'
+  workflow_dispatch:
+
+concurrency:
+  group: source-checks-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  python:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: python -m pip install -e '.[dev]' numpy onnx onnxruntime
+      - run: python tools/prepare_public_release.py
+      - run: ruff check .
+      - run: python -m pytest -q
+  typescript:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: sdk/typescript
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: sdk/typescript/package-lock.json
+      - run: npm ci
+      - run: npm test
+      - run: npm run build:browser
+      - run: npm run build:benchmark
+      - run: npm run build:parity

.gitignore

@@ -0,0 +1,148 @@
+# Public source allowlist. New root paths stay local until explicitly reviewed.
+/*
+!/.gitignore
+!/.gitattributes
+!/.github/
+!/README.md
+!/CONTRIBUTING.md
+!/CITATION.cff
+!/LICENSE
+!/NOTICE
+!/pyproject.toml
+!/configs/
+!/docs/
+!/sdk/
+!/tests/
+!/tools/
+!/vons/
+
+# Internal planning, historical claims and agent/session records stay local.
+/docs/*
+!/docs/KASI_INTEGRATION.md
+!/docs/MODEL_CARD.md
+!/docs/PUBLIC_RELEASE.md
+!/docs/HUGGING_FACE.md
+!/docs/LICENSING.md
+!/docs/COMMUNITY.md
+!/docs/HUB_PUBLISHING.md
+!/docs/publications/
+!/docs/assets/
+/docs/publications/*
+!/docs/publications/README.md
+!/docs/publications/LICENSE.md
+!/docs/publications/ARXIV.md
+/docs/assets/*
+!/docs/assets/inlevel9-signature.png
+!/docs/assets/inlevel9-signature-dark.png
+/configs/*
+!/configs/pilot.json
+!/configs/pilot-diffusion.json
+!/configs/public-release.json
+/sdk/*
+!/sdk/typescript/
+/sdk/typescript/*
+!/sdk/typescript/README.md
+!/sdk/typescript/LICENSE
+!/sdk/typescript/package.json
+!/sdk/typescript/package-lock.json
+!/sdk/typescript/src/
+!/sdk/typescript/test/
+!/sdk/typescript/demo/
+
+# Raw/generated data, weights, evidence packets and local publications.
+data/
+artifacts/
+reports/
+research/
+models/
+weights/
+checkpoints/
+outputs/
+releases/
+private/
+restricted/
+*.onnx
+*.onnx.*
+*.safetensors
+*.gguf
+*.ggml
+*.pt
+*.pth
+*.ckpt
+*.bin
+*.h5
+*.hdf5
+*.npz
+*.npy
+*.pkl
+*.pickle
+*.parquet
+*.arrow
+*.jsonl
+*.zip
+*.tar
+*.tar.*
+*.tgz
+*.7z
+*.dmg
+*.pdf
+# Only the exact reviewed publication bytes are eligible for staging.
+!/docs/publications/vons-paper-v1.0.pdf
+!/docs/publications/vons-tech-report-v1.0.1.pdf
+
+# Credentials, machine-specific config, private prompts and service caches.
+.env
+.env.*
+*.env
+*.pem
+*.key
+*.p12
+*.pfx
+*.jks
+credentials*.json
+secrets*.json
+service-account*.json
+token.json
+.npmrc
+.pypirc
+.netrc
+.aws/
+.ssh/
+.config/
+.cache/
+.huggingface/
+.claude/
+.codex/
+.cursor/
+.trae/
+.idea/
+.vscode/
+*.local.*
+*.log
+*.sqlite*
+*.db
+*.bak
+*.swp
+*~
+.git_backup/
+
+# Environments, dependencies and generated browser bundles.
+.venv/
+venv/
+node_modules/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+.coverage*
+htmlcov/
+coverage/
+build/
+dist/
+*.egg-info/
+/sdk/typescript/demo/*.js
+/sdk/typescript/demo/*.js.map
+.DS_Store
+Thumbs.db

CITATION.cff

@@ -0,0 +1,11 @@
+cff-version: 1.2.0
+message: "If you use this research source, cite this version and the accompanying publications when available."
+type: software
+title: "Vons: Compact Local Decision Models for Frontier-Agent Workflows"
+version: 0.1.0
+authors:
+  - family-names: Ahn
+    given-names: Kwangseob
+    affiliation: "INLEVEL9 / SEJONG UNIV."
+    email: oswarld@inlevel9.com
+abstract: "Research source for bounded local candidate selection and abstention, with host-owned execution and consent."

CONTRIBUTING.md

@@ -0,0 +1,81 @@
+# Contributing to Vons
+
+Help make bounded local decisions easier to understand, reproduce and improve.
+Questions, unsuccessful trials, documentation fixes and small code changes are
+welcome. Start with the [community guide](docs/COMMUNITY.md).
+
+## Choose a contribution
+
+- Share an experience using the **Experience report** issue form. Describe what
+  happened, including failures; a positive result is not required.
+- Submit a **Reproduction report** with exact commands, versions, denominators
+  and the scope of the claim you checked.
+- Use **Bug report** for a minimal, preferably synthetic, reproduction.
+- Propose a focused change through a pull request. Discuss changes to the public
+  contract, data handling, model architecture or dependencies before implementing
+  them. Small documentation corrections can go directly to a pull request.
+
+The intended repository is [inlevel9-com/Jons](https://github.com/inlevel9-com/Jons).
+Its URL spelling differs from the Vons project name. It was private and empty
+when these instructions were prepared; public participation starts after the
+maintainer publishes the reviewed source and verifies the issue forms.
+
+## Work locally
+
+Use Python 3.10 or later. From a source checkout:
+
+```sh
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install -e '.[dev]'
+python -m pytest -q
+ruff check .
+python tools/prepare_public_release.py
+```
+
+On Windows, activate with `.venv\Scripts\Activate.ps1` in PowerShell. Tests for
+optional training/export dependencies may skip explicitly. Do not download
+restricted data or model weights simply to remove a skip. For TypeScript work,
+use the [SDK checks](sdk/typescript/README.md).
+
+Keep one purpose per change. Add behavior-focused regression coverage for fixes.
+Report checks you ran, checks you could not run, and the reason. English is used
+for code, comments and repository documentation; community questions and
+experience reports may be in English or Korean.
+
+## Preserve the boundaries
+
+The general decision contract and the KASI compatibility adapter are separate.
+Model output never executes a tool, grants consent or authorizes a high-risk
+action. Self-reported confidence is not a calibrated probability. Missing
+measurements stay unavailable; design targets are not achieved results.
+
+Use synthetic or redacted examples in public reports. Do not attach credentials,
+private prompts, customer traces, personal data, restricted benchmark rows,
+model weights or private evidence archives. Keep your own raw records locally;
+share only material you are entitled to disclose. Contact
+[oswarld@inlevel9.com](mailto:oswarld@inlevel9.com) before disclosing a security
+issue; the first message should describe the issue without credentials or
+sensitive attachments.
+
+New public files must be reviewed and added to `configs/public-release.json`
+and, where necessary, `.gitignore`. Never force-add ignored research material.
+
+## Review and attribution
+
+Maintainers review scope, correctness, evidence and redistribution rights before
+merging. An issue, testimonial or model-assisted review is not acceptance,
+independent replication or peer review. Review may request changes or decline a
+proposal; no response-time or merge guarantee is implied.
+
+Be specific and respectful. Critique claims and code rather than people. Spam,
+harassment, fabricated evidence and exposed private information may be removed;
+technical criticism and negative results are welcome. Corrections should keep
+the original claim and explain what changed whenever it is safe to do so.
+
+The software uses the [Vons Community and Commercial License](LICENSE), with
+separate [article terms](docs/publications/LICENSE.md). Submitting an issue does
+not grant software-use rights or permission to use it as a promotional quote.
+Code contributions are reviewed for compatibility with the repository license;
+identify third-party material and obtain any required employer permission.
+No copyright assignment or separate contributor agreement is created here.

LICENSE

@@ -0,0 +1,104 @@
+Vons Community and Commercial License 1.0
+SPDX-License-Identifier: LicenseRef-Vons-Community-Commercial-1.0
+
+1. Scope and definitions
+
+"Licensor" means each copyright holder who makes material available under this
+license. "Software" means the Vons-owned source code, configuration, tests and
+supporting software documentation accompanied by this license, including copies
+and modifications. "You" means the individual or legal entity exercising the
+permissions below, including persons acting on that entity's behalf.
+
+This license does not cover material with a separate license notice. In
+particular, the paper and Tech Report and their original research figures are
+licensed separately under CC BY 4.0. Third-party dependencies, upstream model
+assets, datasets, trademarks and logos are not relicensed by this document.
+No model weights or benchmark datasets are supplied with this source release.
+
+"Noncommercial Use" means personal learning, independent noncommercial
+research, or noncommercial education, research or public-benefit activity by a
+nonprofit or educational institution, where the activity is not undertaken for
+commercial advantage, monetary compensation, or on behalf of a business.
+Nonprofit or educational status alone does not make commercial activity
+Noncommercial Use. Unrestricted donations that do not buy a service or benefit
+do not by themselves make an otherwise qualifying activity commercial.
+
+"Commercial Use" includes paid consulting or client work; use in or to support
+a monetized product, service, SaaS, API, hosted or managed service; internal
+business operations; and evaluation, research or deployment by, for, or on
+behalf of a for-profit enterprise. Contractors and affiliates acting for such
+an enterprise require the same permission. Personal use by an employee outside
+their employment, without business benefit, may qualify as Noncommercial Use.
+
+2. Free community permission
+
+Subject to this license, each Licensor grants You a worldwide, nonexclusive,
+royalty-free copyright license to use, reproduce, study, modify, display and
+distribute the Software solely for Noncommercial Use. You may provide access
+to an otherwise qualifying noncommercial service under these conditions.
+Only rights that a Licensor is entitled to grant are included.
+
+3. Redistribution and attribution
+
+When distributing copies or substantial portions of the Software, including
+modified copies or a compiled form, You must:
+
+(a) retain this license, copyright notices and attribution notices;
+(b) clearly identify Your modifications and preserve their provenance;
+(c) identify the Vons version or source revision used where available; and
+(d) convey these same use restrictions for the covered Software, without
+    representing that You can grant Commercial Use rights.
+
+Do not remove notices, misrepresent origin, or imply endorsement by a Licensor,
+INLEVEL9, Sejong University or any other named institution. For research that
+uses Vons, include an appropriate citation to the software and relevant paper
+or Tech Report when reporting results. An unavailable DOI is not required.
+Attribution or citation does not authorize an otherwise restricted use.
+
+4. Enterprise and commercial permission
+
+Commercial Use is not granted by this license. It requires a separate written
+commercial agreement from the relevant Licensor before the activity begins.
+There is no automatic enterprise evaluation or free-trial exception. Contact
+oswarld@inlevel9.com to arrange the scope, fees and permitted entities.
+This license sets no price, billing unit, service level or support commitment.
+A commercial agreement applies only to the parties and scope it identifies.
+
+5. Outputs and independent rights
+
+This license claims no ownership or royalty over Your inference outputs merely
+because they were produced using the Software. Outputs do not authorize an
+unlicensed deployment and may contain material subject to independent rights.
+Your inputs remain subject to their own rights and permissions.
+
+No trademark, logo, certification or endorsement rights are granted, except
+the descriptive use needed to comply with the notices above. No patent license
+is granted by this document. Statutory exceptions and other independently
+obtained permissions are unaffected. This license does not revoke rights
+previously granted under another license for an earlier copy, and does not
+restrict separately licensed third-party components.
+
+6. Termination and cure
+
+Your permissions terminate automatically if You materially breach this
+license. They are reinstated when the breach is cured within 30 days after
+You first discover it, provided this is Your first breach. Otherwise written
+reinstatement from the relevant Licensor is required. Termination does not
+affect compliant recipients' direct permissions or obligations that by their
+nature survive, including the notices and disclaimers below.
+
+7. Warranty disclaimer and liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THE SOFTWARE IS PROVIDED
+"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND
+NONINFRINGEMENT. THE LICENSORS ARE NOT LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY ARISING FROM THE SOFTWARE OR ITS USE, WHETHER IN CONTRACT, TORT OR
+OTHERWISE. NOTHING HERE EXCLUDES LIABILITY THAT CANNOT LAWFULLY BE EXCLUDED.
+
+8. General
+
+Rights not expressly granted are reserved. No later license version applies
+automatically. If a provision is unenforceable, the remaining provisions remain
+in effect to the extent permitted by law. This is a source-available license
+with use restrictions; it is not an OSI-approved open-source license.

README.md

@@ -1,3 +1,93 @@
 ---
-license: apache-2.0
+license: other
+license_name: vons-community-commercial-1.0
+license_link: LICENSE
+language:
+  - en
+tags:
+  - vons
+  - research
+  - candidate-selection
+  - onnx
 ---
+
+![INLEVEL9](docs/assets/inlevel9-signature.png)
+
+# Vons
+
+**Plan globally. Decide locally. Keep the host in control.**
+
+Compact local decision models for frontier-agent workflows.
+
+**Kwangseob Ahn** · **INLEVEL9 / SEJONG UNIV.** · **oswarld@inlevel9.com**
+
+## Source preview
+
+This repository contains research source and documentation. It does not contain
+pretrained model weights, tokenizer assets or datasets. Hosted inference and
+`from_pretrained` loading are not available from this source preview.
+
+Vons studies Direct and Diffusion candidate scoring with abstention. The host
+owns execution, permission and consent. Model output never authorizes an action.
+English-first operation and a model asset budget under 64 MiB are design targets;
+they are not general quality or complete browser-package guarantees.
+
+See [the model card](docs/MODEL_CARD.md),
+[the TypeScript SDK](sdk/typescript/README.md),
+[the paper and Tech Report](docs/publications/README.md), and
+[release preparation](docs/PUBLIC_RELEASE.md).
+
+## Read, try and contribute
+
+This source preview is distributed through [INLEVEL9/Vons](https://huggingface.co/INLEVEL9/Vons).
+Source and contribution reports belong in
+[inlevel9-com/Vons](https://github.com/inlevel9-com/Vons). The reviewed paper and Tech Report are included as PDF downloads below. The software remains a 0.1.0
+research preview. No pretrained weights or working Space are announced.
+
+Follow the [community guide](docs/COMMUNITY.md) for the no-weight walkthrough,
+experience and reproduction reports, and the
+[contribution guide](CONTRIBUTING.md) for review expectations. The paper is
+being prepared for [arXiv](docs/publications/ARXIV.md). User reports are not
+independent research validation.
+
+Maintainers can use the [Hub upload guide](docs/HUB_PUBLISHING.md) to prepare
+an organization card, source preview and later a separately validated Space.
+
+## Paper and Tech Report
+
+| Publication | Download |
+| --- | --- |
+| Vons: A Compact, Host-Controlled Decision Component for Agent Workflows — paper v1.0, final editorial revision | [PDF · 15 pages](docs/publications/vons-paper-v1.0.pdf) |
+| Vons: Compact Decision Models for Frontier-Agent Workflows — Technical Report v1.0.1 | [PDF · 20 pages](docs/publications/vons-tech-report-v1.0.1.pdf) |
+
+Articles and original figures use **CC BY 4.0**. Their version, SHA-256 digests
+and verification scope are in the [publication index](docs/publications/README.md).
+These preprints preserve negative results and missing measurements. No arXiv
+identifier or peer-review acceptance is announced.
+
+## Local use
+
+```sh
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install -e '.[dev]'
+python -m vons.cli generate-smoke --output data/generated/smoke.jsonl
+python -m vons.cli validate-data --input data/generated/smoke.jsonl
+```
+
+The source export includes the research tools and pinned pilot configurations.
+Obtain and review upstream assets separately before running model experiments.
+Raw restricted benchmark data and private evidence are not redistributed here.
+
+## Terms
+
+Source is distributed under [Vons Community and Commercial License 1.0](LICENSE):
+qualifying noncommercial use is free; enterprise and other commercial use require
+a separate written agreement. Contact oswarld@inlevel9.com for commercial terms.
+This is source-available software, not OSI-approved open source.
+
+The paper and Tech Report are distributed under [CC BY 4.0](docs/publications/LICENSE.md).
+This permits commercial article reuse with attribution; software rights are
+separate. Third-party assets retain their own terms. See
+[licensing scope](docs/LICENSING.md). This source release does not establish research validation or a commercial
+customer agreement.

configs/pilot-diffusion.json

@@ -0,0 +1,16 @@
+{
+  "model_id": "vons-pilot-diffusion",
+  "backend": "diffusion",
+  "option_count": 32,
+  "encoder": {"name": "google/bert_uncased_L-4_H-256_A-4", "revision": "387825ce42dbb39b87911cdf8e383ee3b25184f8", "max_tokens": 512},
+  "data": {"path": "data/generated/pilot.jsonl", "manifest": "artifacts/pilot-diffusion/data-manifest.json"},
+  "seed": 7,
+  "epochs": 3,
+  "batch_size": 16,
+  "learning_rate": 0.00005,
+  "diffusion_steps": 32,
+  "inference_steps": 4,
+  "device": "auto",
+  "artifact_dir": "artifacts/pilot-diffusion",
+  "target_bundle_bytes": 67108864
+}

configs/pilot.json

@@ -0,0 +1,15 @@
+{
+  "model_id": "vons-pilot-direct",
+  "backend": "direct",
+  "option_count": 32,
+  "encoder": {"name": "google/bert_uncased_L-4_H-256_A-4", "revision": "387825ce42dbb39b87911cdf8e383ee3b25184f8", "max_tokens": 512},
+  "data": {"path": "data/generated/pilot.jsonl", "manifest": "artifacts/pilot/data-manifest.json"},
+  "seed": 7,
+  "epochs": 3,
+  "batch_size": 16,
+  "learning_rate": 0.00005,
+  "diffusion_steps": 32,
+  "inference_steps": 4,
+  "device": "auto",
+  "target_bundle_bytes": 67108864
+}

configs/public-release.json

@@ -0,0 +1,111 @@
+{
+  "schema": "vons.public-source-spec/v1",
+  "license_status": "owner_selected_custom_terms_prepared",
+  "files": [
+    ".gitattributes",
+    ".github/ISSUE_TEMPLATE/bug.yml",
+    ".github/ISSUE_TEMPLATE/experience.yml",
+    ".github/ISSUE_TEMPLATE/reproduction.yml",
+    ".github/PULL_REQUEST_TEMPLATE.md",
+    ".github/workflows/checks.yml",
+    ".gitignore",
+    "CITATION.cff",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "README.md",
+    "configs/pilot-diffusion.json",
+    "configs/pilot.json",
+    "configs/public-release.json",
+    "docs/COMMUNITY.md",
+    "docs/HUB_PUBLISHING.md",
+    "docs/HUGGING_FACE.md",
+    "docs/KASI_INTEGRATION.md",
+    "docs/LICENSING.md",
+    "docs/MODEL_CARD.md",
+    "docs/PUBLIC_RELEASE.md",
+    "docs/assets/inlevel9-signature-dark.png",
+    "docs/assets/inlevel9-signature.png",
+    "docs/publications/ARXIV.md",
+    "docs/publications/LICENSE.md",
+    "docs/publications/README.md",
+    "docs/publications/vons-paper-v1.0.pdf",
+    "docs/publications/vons-tech-report-v1.0.1.pdf",
+    "pyproject.toml",
+    "sdk/typescript/LICENSE",
+    "sdk/typescript/README.md",
+    "sdk/typescript/demo/benchmark.html",
+    "sdk/typescript/demo/benchmark.ts",
+    "sdk/typescript/demo/index.html",
+    "sdk/typescript/demo/main.ts",
+    "sdk/typescript/demo/parity.html",
+    "sdk/typescript/demo/parity.ts",
+    "sdk/typescript/package-lock.json",
+    "sdk/typescript/package.json",
+    "sdk/typescript/src/index.ts",
+    "sdk/typescript/src/onnx.ts",
+    "sdk/typescript/test/index.test.mjs",
+    "sdk/typescript/test/onnx.test.mjs",
+    "sdk/typescript/test/parity.test.mjs",
+    "tests/test_browser_benchmark.py",
+    "tests/test_browser_benchmark_summary.py",
+    "tests/test_browser_parity_reference.py",
+    "tests/test_bundle.py",
+    "tests/test_calibration.py",
+    "tests/test_contract.py",
+    "tests/test_data.py",
+    "tests/test_evaluation.py",
+    "tests/test_merge_browser_benchmarks.py",
+    "tests/test_mind2web.py",
+    "tests/test_mind2web_import.py",
+    "tests/test_mind2web_manifest.py",
+    "tests/test_mind2web_prediction.py",
+    "tests/test_mind2web_replay.py",
+    "tests/test_mind2web_runner.py",
+    "tests/test_public_release.py",
+    "tests/test_quality_summary.py",
+    "tests/test_regression.py",
+    "tests/test_shape_benchmark.py",
+    "tests/test_shared_bundle.py",
+    "tools/archive_manifest.py",
+    "tools/audit_local_model_alignment.py",
+    "tools/benchmark_onnx_bundle.py",
+    "tools/benchmark_onnx_shapes.py",
+    "tools/build_claim_ledger.py",
+    "tools/build_mind2web_manifest.py",
+    "tools/evaluate_mind2web.py",
+    "tools/export_shared_bundle.py",
+    "tools/freeze_publication_packet.py",
+    "tools/import_mind2web.py",
+    "tools/merge_browser_benchmarks.py",
+    "tools/predict_mind2web.py",
+    "tools/prepare_public_release.py",
+    "tools/recover_historical_manifest.py",
+    "tools/replay_mind2web_evaluation.py",
+    "tools/summarize_browser_benchmark.py",
+    "tools/summarize_quality.py",
+    "tools/verify_browser_benchmark.py",
+    "tools/verify_browser_parity.py",
+    "tools/verify_onnx_bundle.py",
+    "vons/__init__.py",
+    "vons/bundle.py",
+    "vons/calibration.py",
+    "vons/cli.py",
+    "vons/contract.py",
+    "vons/data.py",
+    "vons/evaluation.py",
+    "vons/kasi.py",
+    "vons/mind2web.py",
+    "vons/models.py",
+    "vons/ollama.py",
+    "vons/research.py",
+    "vons/training.py"
+  ],
+  "reviewed_binaries": {
+    "docs/assets/inlevel9-signature.png": "f7514b56b2a93293054b3d22634ac5f0cb11e00a370f53d8d9f934c55a21bbb5",
+    "docs/assets/inlevel9-signature-dark.png": "d6645528158842af77a89de97361fa0c521fbc5a3c0ea6e996f9c912cfcfe9b5",
+    "docs/publications/vons-paper-v1.0.pdf": "ae0e09c60e17a98b52bb25c611b2489d10b18bd98d87974f2e8dd25d746a5fc8",
+    "docs/publications/vons-tech-report-v1.0.1.pdf": "33076d9e52d4a073060066215dd390e3b0bf0cdef48c5ffb2a7c5189854254ed"
+  },
+  "software_license": "LicenseRef-Vons-Community-Commercial-1.0",
+  "article_license": "CC-BY-4.0"
+}

docs/COMMUNITY.md

@@ -0,0 +1,115 @@
+# Read, try, share and contribute
+
+Vons explores compact local decisions inside agent workflows. A planner supplies
+state and bounded candidates; the host retains execution, policy and consent.
+The community should help people understand this boundary, try the software and
+report what works or fails.
+
+## Start here
+
+| Your goal | Entry point | Current availability |
+| --- | --- | --- |
+| Understand Vons | [README](../README.md) and [model card](MODEL_CARD.md) | Included in this source preview |
+| Read the research | [Paper and Tech Report](publications/README.md) | Coming soon; v1.0 manuscripts are in preparation and excluded from this release |
+| Try without weights | The walkthrough below | Deterministic contract and synthetic data only |
+| Run model inference | [TypeScript SDK](../sdk/typescript/README.md) | Requires separately obtained, reviewed model/tokenizer assets |
+| Share experience | [Experience report](https://github.com/inlevel9-com/Vons/issues/new?template=experience.yml) | GitHub account required to submit |
+| Reproduce a result | [Reproduction report](https://github.com/inlevel9-com/Vons/issues/new?template=reproduction.yml) | Form included; evidence reviewed separately |
+| Improve Vons | [Contributing](../CONTRIBUTING.md) | Documentation, tests and scoped code changes welcome |
+
+The destinations are [GitHub: inlevel9-com/Vons](https://github.com/inlevel9-com/Vons)
+and [Hugging Face: INLEVEL9/Vons](https://huggingface.co/INLEVEL9/Vons).
+The source preview includes documentation and GitHub issue forms for feedback.
+The paper and Tech Report will be added after v1.0 review; this release contains
+neither manuscript. A source upload does not provide hosted model inference.
+The current software terms require a separate agreement for
+enterprise/commercial use, including enterprise evaluation. Reading the paper
+under its article terms is separate from software use.
+
+## A five-minute first exploration
+
+Five minutes is a usability target, not a measured onboarding result. Start in
+the root of a source checkout with Python 3.10+. This path needs no model assets,
+GPU, API token or hosted inference account. Python packaging may need internet
+access to install its build tools.
+
+```sh
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install -e .
+python -m vons.cli generate-smoke --output data/generated/community-smoke.jsonl
+python -m vons.cli validate-data --input data/generated/community-smoke.jsonl
+```
+
+On Windows PowerShell use `.venv\Scripts\Activate.ps1` for activation. The
+generator reports four synthetic rows. Validation prints their data manifest;
+this checks the data contract, not model quality.
+
+Run this Python example in the same environment:
+
+```python
+from vons import KASIAdapter, KASIProposal
+
+adapter = KASIAdapter(tool_policy={"read_weather": "low"})
+for tool in ("read_weather", "unknown_tool"):
+    proposal = KASIProposal.from_mapping({
+        "calls": [{"name": tool}],
+        "confidence": 0.9,
+        "risk": "low",
+    })
+    decision = adapter.decide(proposal)
+    print(tool, decision.action.value, decision.reason)
+```
+
+Expected output:
+
+```text
+read_weather call approved_by_host_policy
+unknown_tool refuse unregistered_or_no_proposed_call
+```
+
+This is the deterministic KASI adapter, not a learned Vons prediction. The word
+`call` is a returned decision; the example never fetches weather or executes a
+tool. The host supplies the tool policy. The literal confidence is sample input,
+not a calibrated probability. See the [general scope](MODEL_CARD.md) and
+[KASI integration](KASI_INTEGRATION.md) before building an integration.
+
+## Share an honest experience
+
+Use a report form with the source revision or release-manifest digest, scenario,
+OS/device, runtime/provider, exact command, expected behavior and observed
+behavior. Mark whether you tried the contract, a synthetic example or real model
+inference. Include attempted, successful, abstained and failed counts with
+definitions; explain any overlapping categories. Report unavailable quantities
+as unavailable and keep errors in the denominator.
+
+A short negative report is useful. Personal experience and measured benchmarks
+serve different purposes: user ratings, stars and downloads do not establish
+accuracy, safety or independent replication. Public reports are not automatically
+training data or promotional testimonials. Link only safe evidence you have
+reviewed and have permission to share. No name, employer or private workflow is
+required beyond the hosting service's account requirements.
+
+## A practical platform roadmap
+
+These are proposed acceptance criteria, not completed or measured milestones.
+
+1. **Reading and participation:** publish a reviewed source preview, readable
+   research summary and accurate availability notices. A signed-out visitor can
+   read the documentation; a signed-in contributor can submit each issue form
+   and find the contribution rules. Check keyboard navigation and narrow screens.
+2. **First use:** test the no-weight walkthrough from a clean checkout. Invite
+   voluntary reports of completion, failure and time spent. Keep counts and
+   denominators; do not infer actual use from page views or stars.
+3. **Real inference:** offer a versioned demo only after permitted model assets,
+   tokenizer, notices, provider evidence and numerical parity are reviewed.
+   Clearly label unsupported requests and known failures. Host policy still
+   controls actions. Do not present static or simulated results as inference.
+4. **Community learning:** triage reports, publish reproducible improvements,
+   credit contributions and keep corrections visible. Record submitted reports,
+   independently reproduced reports and accepted contributions separately.
+
+Start with the existing GitHub and Hugging Face channels. A dedicated website,
+review database, accounts and telemetry need a separate implementation decision;
+none is required for the first source preview. Reading should remain available
+without a Vons account. Follow the [contribution and moderation rules](../CONTRIBUTING.md).

docs/HUB_PUBLISHING.md

@@ -0,0 +1,118 @@
+# Upload the Vons source preview to Hugging Face
+
+This is an owner-operated upload guide. The current local preparation contains
+97 reviewed files, including the final paper and Tech Report PDFs. Drafts,
+source manuscript bundles, model weights, restricted data and private records
+are excluded.
+
+## Destination and scope
+
+Use the existing model repository [INLEVEL9/Vons](https://huggingface.co/INLEVEL9/Vons).
+The organization page [INLEVEL9](https://huggingface.co/INLEVEL9) is its parent,
+not a folder-upload destination. There is no need to create another repository,
+a dataset or a Space for this source preview.
+
+At the last read-only check on 2026-09-25, the Hub repository was public and
+contained only `.gitattributes` and a minimal Apache-2.0 README. The prepared
+root README and LICENSE replace that placeholder with the selected Vons
+Community and Commercial License 1.0. The article CC BY 4.0 terms are separate.
+
+A commit to this public repository makes uploaded files publicly readable.
+Uploading source does not create hosted inference, pretrained weights or a
+working `from_pretrained` package. The card states those limits explicitly.
+The main code/contribution destination is
+[inlevel9-com/Vons](https://github.com/inlevel9-com/Vons). Its visibility is
+controlled separately from Hugging Face.
+
+## 1. Install and sign in
+
+On macOS with Homebrew:
+
+```sh
+brew install hf
+hf auth login
+hf auth whoami
+```
+
+If Homebrew already installed `hf`, use `brew upgrade hf` when an update is
+needed. Current CLI versions offer browser login: follow the displayed URL and
+code, and sign in using your account with write access to `INLEVEL9/Vons`.
+`hf auth whoami` confirms the account and organization membership; membership
+alone does not guarantee repository write permission.
+
+If your CLI asks for a token instead, create a user access token in
+[Hugging Face token settings](https://huggingface.co/settings/tokens), preferably
+scoped to write to `INLEVEL9/Vons`, and enter it at the hidden login prompt.
+Keep credentials out of source files, shell command arguments and issue reports.
+See the official [CLI guide](https://huggingface.co/docs/huggingface_hub/guides/cli).
+
+## 2. Use the reviewed export
+
+Run the source audit from the Vons checkout:
+
+```sh
+python3 tools/prepare_public_release.py
+```
+
+The current prepared upload folder is `releases/huggingface-source-v8`.
+It contains the 97 reviewed files plus a local `RELEASE_MANIFEST.json` receipt
+with every file's byte count and SHA-256 digest. Its root README is the Hub model
+card; the working-tree README remains the GitHub landing page.
+
+This export is a snapshot. If you edit any public source or documentation after
+preparation, create a fresh versioned directory and use that path below:
+
+```sh
+python3 tools/prepare_public_release.py --target huggingface --output releases/huggingface-source-v9
+```
+
+The exporter refuses to overwrite an existing directory. Never point the upload
+command at the development checkout or an old export containing stale terms.
+
+## 3. Upload
+
+From the Vons checkout, after reviewing the v8 export:
+
+```sh
+hf upload INLEVEL9/Vons releases/huggingface-source-v8 . \
+  --repo-type model \
+  --exclude RELEASE_MANIFEST.json \
+  --commit-message "Publish Vons source preview and reviewed research PDFs"
+```
+
+The final `.` places the files at the repository root while preserving nested
+paths. The command creates a Hub commit directly; a separate Git commit/push
+is unnecessary. It updates matching remote paths, including README and LICENSE,
+and does not request deletion of unrelated remote files. The manifest stays
+local as an audit receipt; it is not an additional source file in the allowlist.
+
+A successful command prints a repository or commit URL. For a 401/403 response,
+check the account, `INLEVEL9/Vons` write permission and credential scope; do not
+create a duplicate personal repository. Official
+[upload guidance](https://huggingface.co/docs/huggingface_hub/guides/upload)
+describes folder uploads and filtering.
+
+## 4. Verify the result
+
+Open [the model card](https://huggingface.co/INLEVEL9/Vons) and
+[Files and versions](https://huggingface.co/INLEVEL9/Vons/tree/main):
+
+- The card says this is a source preview with no pretrained weights or hosted inference.
+- License metadata uses `other`, `vons-community-commercial-1.0` and `LICENSE`.
+  It must no longer identify the software as Apache-2.0 or CC BY 4.0.
+- Root `LICENSE` and `sdk/typescript/LICENSE` contain the same custom terms.
+- Source paths such as `vons/`, `tools/`, `tests/` and `sdk/typescript/` are present.
+- The Paper and Tech Report links open the 15-page paper and 20-page report.
+  Their digests match the publication index. No manuscript source bundle or
+  private review material is uploaded.
+- Logo/documentation links resolve, and a signed-out visitor can read the card.
+
+Save the resulting Hub commit URL with the local release manifest. GitHub
+publication, manuscript publication and a hosted demo are separate actions.
+For subsequent source changes, create a new reviewed export and repeat the same
+upload command with its new path. Add research files only after their separate
+v1.0 review and an explicit public-allowlist update.
+
+The owner performs authentication, commit, push and publication. This local
+preparation has not executed an upload or changed remote visibility.
+Official CLI/upload guidance checked 2026-09-25.

docs/HUGGING_FACE.md

@@ -0,0 +1,93 @@
+---
+license: other
+license_name: vons-community-commercial-1.0
+license_link: LICENSE
+language:
+  - en
+tags:
+  - vons
+  - research
+  - candidate-selection
+  - onnx
+---
+
+![INLEVEL9](../docs/assets/inlevel9-signature.png)
+
+# Vons
+
+**Plan globally. Decide locally. Keep the host in control.**
+
+Compact local decision models for frontier-agent workflows.
+
+**Kwangseob Ahn** · **INLEVEL9 / SEJONG UNIV.** · **oswarld@inlevel9.com**
+
+## Source preview
+
+This repository contains research source and documentation. It does not contain
+pretrained model weights, tokenizer assets or datasets. Hosted inference and
+`from_pretrained` loading are not available from this source preview.
+
+Vons studies Direct and Diffusion candidate scoring with abstention. The host
+owns execution, permission and consent. Model output never authorizes an action.
+English-first operation and a model asset budget under 64 MiB are design targets;
+they are not general quality or complete browser-package guarantees.
+
+See [the model card](../docs/MODEL_CARD.md),
+[the TypeScript SDK](../sdk/typescript/README.md),
+[the paper and Tech Report](../docs/publications/README.md), and
+[release preparation](../docs/PUBLIC_RELEASE.md).
+
+## Read, try and contribute
+
+This source preview is distributed through [INLEVEL9/Vons](https://huggingface.co/INLEVEL9/Vons).
+Source and contribution reports belong in
+[inlevel9-com/Vons](https://github.com/inlevel9-com/Vons). The reviewed paper and Tech Report are included as PDF downloads below. The software remains a 0.1.0
+research preview. No pretrained weights or working Space are announced.
+
+Follow the [community guide](../docs/COMMUNITY.md) for the no-weight walkthrough,
+experience and reproduction reports, and the
+[contribution guide](../CONTRIBUTING.md) for review expectations. The paper is
+being prepared for [arXiv](../docs/publications/ARXIV.md). User reports are not
+independent research validation.
+
+Maintainers can use the [Hub upload guide](../docs/HUB_PUBLISHING.md) to prepare
+an organization card, source preview and later a separately validated Space.
+
+## Paper and Tech Report
+
+| Publication | Download |
+| --- | --- |
+| Vons: A Compact, Host-Controlled Decision Component for Agent Workflows — paper v1.0, final editorial revision | [PDF · 15 pages](../docs/publications/vons-paper-v1.0.pdf) |
+| Vons: Compact Decision Models for Frontier-Agent Workflows — Technical Report v1.0.1 | [PDF · 20 pages](../docs/publications/vons-tech-report-v1.0.1.pdf) |
+
+Articles and original figures use **CC BY 4.0**. Their version, SHA-256 digests
+and verification scope are in the [publication index](../docs/publications/README.md).
+These preprints preserve negative results and missing measurements. No arXiv
+identifier or peer-review acceptance is announced.
+
+## Local use
+
+```sh
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install -e '.[dev]'
+python -m vons.cli generate-smoke --output data/generated/smoke.jsonl
+python -m vons.cli validate-data --input data/generated/smoke.jsonl
+```
+
+The source export includes the research tools and pinned pilot configurations.
+Obtain and review upstream assets separately before running model experiments.
+Raw restricted benchmark data and private evidence are not redistributed here.
+
+## Terms
+
+Source is distributed under [Vons Community and Commercial License 1.0](../LICENSE):
+qualifying noncommercial use is free; enterprise and other commercial use require
+a separate written agreement. Contact oswarld@inlevel9.com for commercial terms.
+This is source-available software, not OSI-approved open source.
+
+The paper and Tech Report are distributed under [CC BY 4.0](../docs/publications/LICENSE.md).
+This permits commercial article reuse with attribution; software rights are
+separate. Third-party assets retain their own terms. See
+[licensing scope](../docs/LICENSING.md). This source release does not establish research validation or a commercial
+customer agreement.

docs/KASI_INTEGRATION.md

@@ -0,0 +1,44 @@
+# KASI integration in Vons
+
+KASI is the first Vons domain adapter, not a separate model product. Vons owns
+the general candidate judgment contract; the adapter preserves KASI's public
+five-action contract for tool-calling hosts:
+
+`call`, `clarify`, `confirm`, `refuse`, `respond`.
+
+The model may propose ordinary calls, clarification, refusal, or a response. It
+cannot grant consent. The host wrapper requires a host-owned registry of tool
+names and risk levels, validates tools and arguments, applies confidence
+thresholds, and derives `confirm` from that policy. The proposal's `risk` is
+only advisory: it can never lower the registered host risk, and missing or
+unknown risk is fail-closed. The host remains the only execution boundary.
+
+Consent is bound to the complete call, including its arguments. Pass the
+`KASICall.fingerprint()` returned for the exact call in `confirmed_calls`; a
+tool name in `confirmed_tools` is retained only for compatibility and cannot
+authorize a high-risk call.
+
+The Python adapter stores a SHA-256 fingerprint. The TypeScript SDK exposes the
+same canonical `{name, arguments}` consent key as a portable string because
+browser runtimes do not provide synchronous SHA-256. A host that shares consent
+records between the Python and TypeScript adapters must hash the TypeScript key
+with SHA-256 before persistence and comparison.
+
+Unregistered tools are refused. A minimal host setup is:
+
+```python
+from vons import KASIAdapter, KASICall, KASIProposal
+
+adapter = KASIAdapter(tool_policy={"read_weather": "low", "unlock": "high"})
+proposal = KASIProposal(
+    calls=(KASICall("read_weather", {"city": "Seoul"}),),
+    confidence=0.9,
+    risk="low",
+)
+decision = adapter.decide(proposal)
+```
+
+The mapping is intentionally one-way: KASI calls can be represented as Vons
+choices, but arbitrary Vons choices do not become tool calls without a host
+adapter. Existing KASI datasets, safety policy, and C99 adapter can be imported
+behind a manifest when their provenance and licensing are recorded.

docs/LICENSING.md

@@ -0,0 +1,42 @@
+# Licensing and distribution scope
+
+The owner selected these terms on 2026-09-24. This local preparation is ready
+for owner-controlled source distribution:
+
+| Material | Terms |
+|---|---|
+| Vons-owned source, tests, configurations and software documentation | [Vons Community and Commercial License 1.0](../LICENSE) |
+| Paper, Tech Report and their original research figures | [CC BY 4.0](publications/LICENSE.md) |
+| Third-party libraries, upstream encoders/tokenizers and datasets | Their original terms; no relicense |
+| INLEVEL9 logo and other marks | No general trademark license or endorsement |
+| Model weights, restricted data and private evidence | Excluded from this source release |
+
+The free software grant covers qualifying noncommercial personal, educational,
+nonprofit research and public-benefit use. Enterprise use, including internal
+evaluation, and other commercial use require a separate written agreement.
+Paid consulting, client work, SaaS/API hosting and embedding in a commercial
+product fall in that category. Contact [oswarld@inlevel9.com](mailto:oswarld@inlevel9.com)
+for the scope and commercial terms; no price or automatic trial is specified.
+
+This is **source-available software**, not OSI-approved open source. The article
+license is deliberately separate: CC BY 4.0 permits commercial article reuse
+with its attribution conditions, without granting commercial software rights.
+Affiliation is attribution and does not establish institutional endorsement.
+
+## Transition and distribution
+
+Earlier local Python metadata declared Apache-2.0. This source release
+uses `LicenseRef-Vons-Community-Commercial-1.0` and includes its exact text.
+Frozen research snapshots retain their historical metadata and measurements.
+This change makes no claim that rights previously granted under Apache-2.0 can
+be withdrawn. Existing third-party licenses and notices remain effective.
+
+The root license contains the custom terms for this source distribution.
+A separate written agreement is required for enterprise or commercial software
+use; publishing the source does not execute a customer contract. The source
+list and hashes identify the reviewed files, and do not establish rights over
+an unreviewed third-party asset. No manuscript or model weights accompany this
+source release.
+
+Commercial contracts, pricing, support and optional conformance services are
+separate from this free community grant. No certification claim is made.

docs/MODEL_CARD.md

@@ -0,0 +1,54 @@
+# Vons model card
+
+Status: research source preview. This package contains no pretrained weights,
+tokenizer files or benchmark datasets.
+
+## Intended use
+
+Vons studies bounded candidate selection and abstention in agent workflows.
+A host supplies the state and candidates. The host alone enforces permission,
+consent and execution policy. KASI is a separate compatibility adapter.
+
+## Architecture and target
+
+The research implementation offers a Direct scorer and a conditional Diffusion
+scorer. Pilot configurations pin `google/bert_uncased_L-4_H-256_A-4` at revision
+`387825ce42dbb39b87911cdf8e383ee3b25184f8`. This identifies a research dependency;
+its assets are not included or relicensed here.
+
+English-first input and a model asset budget below 64 MiB are design targets.
+Runtime libraries, complete download size and memory use are distinct quantities.
+
+## Evaluation and limitations
+
+Historical local experiments include synthetic pilots and an evaluation-only
+external benchmark diagnostic. They do not establish general task quality,
+production readiness, calibrated safety or a Direct/Diffusion superiority claim.
+Reviewed numerical claims belong to the versioned
+[paper and Tech Report](publications/README.md), with exact evidence references.
+Unreviewed historical tables are not distributed as current results.
+
+The ONNX candidate head does not support general score questions. Python and
+TypeScript token-budget checks are not fully identical. Browser smoke, repeated
+latency, full numerical parity and memory evidence remain separate gates.
+
+Do not use model confidence as a permission grant or assume it is calibrated.
+Vons cannot execute tools or approve high-risk actions.
+
+## Data and provenance
+
+Synthetic data can be generated from the source. Restricted data, model-generated
+raw responses, private prompts, model checkpoints and local manifests are
+excluded from this distribution. Obtain any external dataset under its own
+terms. The source release manifest records hashes of the files actually exported.
+
+## Author and terms
+
+Kwangseob Ahn — INLEVEL9 / SEJONG UNIV. — oswarld@inlevel9.com.
+
+The Vons-owned source is prepared under [Vons Community and Commercial License
+1.0](../LICENSE): noncommercial community use is free; enterprise/commercial use
+requires a separate written agreement. The articles and their original figures
+use [CC BY 4.0](publications/LICENSE.md). Third-party assets retain their own
+terms, and no model weights are licensed or included by this source-only card.
+See [licensing scope](LICENSING.md) and [release preparation](PUBLIC_RELEASE.md).

docs/PUBLIC_RELEASE.md

@@ -0,0 +1,94 @@
+# Public source release
+
+The public source set is defined by `configs/public-release.json`. The root
+`.gitignore` excludes unreviewed root paths and internal documents; the release
+tool independently rejects any Git candidate outside that exact file list.
+
+## Included and excluded material
+
+Included: Python and TypeScript source, tests, source demo files, the SDK
+dependency lockfile, pilot configuration, reviewed public documentation and the
+owner-supplied INLEVEL9 logo. Reviewed publications are listed separately in
+`docs/publications/README.md`.
+
+Excluded: all local datasets (including synthetic outputs), model weights,
+tokenizers, ONNX external-data shards, experiment reports, evidence archives,
+private prompts and raw model responses, agent/session records, license drafts,
+historical planning documents, generated demo JavaScript, environments,
+credentials, service caches and unreviewed binary files. Keep excluded originals
+locally; never force-add them to make an upload work.
+
+## Audit and export
+
+Run from the repository root with Python 3.10+ and Git:
+
+```sh
+python tools/prepare_public_release.py
+python tools/prepare_public_release.py --target github --output releases/github-source
+python tools/prepare_public_release.py --target huggingface --output releases/huggingface-source
+```
+
+Each export is a new directory containing only allowlisted files and a
+`RELEASE_MANIFEST.json` with byte counts and SHA-256 hashes. Existing output
+directories are never overwritten. Use a new versioned output path after any
+source change. The Hugging Face export substitutes its model card as the root
+README. Both exports contain source and the two exact reviewed publication PDFs, with
+no pretrained assets.
+
+The audit detects known token/key patterns, personal home paths, private writing
+session URLs, unexpected Git files, symlinks and changed reviewed binaries.
+Pattern scanning is heuristic: passing it is not a complete secret audit or
+proof of redistribution rights. Read the actual export before publishing.
+
+## GitHub
+
+The source checkout uses `main`; review `git status`, the existing commit history
+and the export manifest before publishing changes. The owner performs commits,
+pushes and visibility changes. This preparation does not perform those actions. Preserve a clean initial tree: `.gitignore` cannot
+remove already committed material from history. If existing remote history is
+later attached, review that history independently before making it public.
+
+The CI workflow checks the release allowlist, Python tests and lint, and the SDK
+tests and three browser builds. Push/pull-request checks run when source,
+tests, configuration or the workflow changes; documentation-only edits do not
+trigger the full suite. A manual run remains available. SDK tokenizer tests use
+synthetic fixtures and require no private pilot assets. It has read-only repository permissions and
+does not publish packages or artifacts. Checks that require unavailable optional
+Python dependencies may be skipped; install training/export extras for the full
+local suite. The historical pilot-summary regression is also skipped when its
+private input files are absent. A separate synthetic regression runs without
+those files; do not publish the historical inputs merely to remove that skip.
+
+## Hugging Face
+
+Upload only a reviewed versioned Hugging Face export to `INLEVEL9/Vons`.
+The current preparation is `releases/huggingface-source-v8`; see the
+[step-by-step upload guide](HUB_PUBLISHING.md). Do not select the development workspace in the
+Hub upload dialog. Use explicit allow/ignore patterns if using `upload_folder`;
+its handling of ignore files depends on the client version and upload method.
+
+This source preview has no weights and no inference widget. A later weight
+release needs its own exact file inventory, upstream notices, model/data
+provenance and runtime validation. Do not turn the ignored checkpoint directory
+into a public upload by adding Git LFS patterns.
+
+Official references: [GitHub ignore guidance](https://docs.github.com/en/get-started/getting-started-with-git/ignoring-files)
+and [Hub upload guidance](https://huggingface.co/docs/huggingface_hub/guides/upload).
+
+## Terms and publication state
+
+The owner selected noncommercial-free / enterprise-commercial software terms
+and CC BY 4.0 articles on 2026-09-24. The prepared root [license](../LICENSE), SDK
+license copy, package metadata and Hub card now match that source-available
+direction. [Licensing scope](LICENSING.md) explains the boundary and preserves
+earlier and third-party rights. Local preparation is complete for the owner to
+commit, push and publish; no commercial customer agreement is adopted here.
+npm publishing remains disabled with `private: true`.
+
+The Python build backend requires setuptools 77.0.3+ to include the custom SPDX
+license reference and exact license file in wheel/sdist metadata. No runtime
+dependency was added. Verify built package contents as well as source exports.
+
+The author-approved public contact is Kwangseob Ahn, oswarld@inlevel9.com,
+INLEVEL9 / SEJONG UNIV. Logo inclusion does not grant trademark rights or imply
+institutional endorsement. Model-assisted writing/review is not peer acceptance.

docs/publications/ARXIV.md

@@ -0,0 +1,67 @@
+# arXiv preparation
+
+The [reviewed paper PDF](vons-paper-v1.0.pdf) is included in the source release,
+alongside the [Technical Report](vons-tech-report-v1.0.1.pdf). arXiv submission
+is being prepared; no arXiv identifier or acceptance is announced. arXiv performs
+content moderation, not journal peer review; see its
+[moderation policy](https://info.arxiv.org/help/moderation/index.html).
+
+## Current preparation
+
+Exact local PDF hashes match the reviewed final manuscripts, and all 35 pages
+have been inspected. The documents were generated with Typst, not TeX/LaTeX.
+The paper is being prepared for the genuine non-TeX PDF submission route,
+subject to arXiv's processing checks. An independent source rebuild remains
+unverified; see the [publication index](README.md) for exact verification scope.
+Historical drafts and claim-to-source records remain private.
+
+## Research scope
+
+Present the bounded decision contract, engineering evidence and informative
+negative results. State the synthetic pilot's label imbalance and baseline,
+external-evaluation failures, token budget and browser-verification limitations
+alongside the relevant results. A narrower research preprint can describe open
+engineering gates without claiming that those gates have passed or that a model
+is ready for deployment. Preserve a separate private claim-to-source audit.
+
+The publication language is English. Author metadata is **Kwangseob Ahn**,
+**INLEVEL9 / SEJONG UNIV.**, **oswarld@inlevel9.com**. Article preparation uses
+[CC BY 4.0](LICENSE.md); software terms are separate. The author remains
+responsible for scientific claims, references and model-assistance disclosure.
+
+## Files and checks
+
+Prepare a readable PDF, editable manuscript source, included figures and
+bibliography, together with a reproducible build instruction. Verify every
+source-bundle entry and record exact hashes. Resolve missing references,
+orphan captions, table breaks and unavailable figures; inspect all PDF pages.
+Keep private claim ledgers, prompts, review conversations, restricted benchmark
+rows and unrelated repository files outside the submission bundle.
+
+arXiv prefers TeX/LaTeX and requires source when the PDF was made from TeX/LaTeX.
+Include figure files instead of external figure links. See the official
+[submission overview](https://info.arxiv.org/help/submit/index.html).
+For a genuine non-TeX PDF, follow the [PDF requirements](https://info.arxiv.org/help/submit_pdf.html),
+including embedded outline fonts and no encryption or active content.
+For a TeX package, include the necessary bibliography source or compatible
+generated bibliography and confirm the top-level file builds from the bundle
+root. Inspect arXiv's processed PDF as well as the local build. See
+[TeX submission guidance](https://info.arxiv.org/help/submit_tex.html).
+
+## Author submission handoff
+
+1. Review the exact final manuscript, source bundle, hashes and remaining limits.
+2. Confirm title, abstract, author affiliation, article rights and a subject
+   category based on the paper's actual contribution. `cs.AI` and `cs.LG` are
+   candidates to assess, not confirmed classifications.
+3. Check the account and any applicable [endorsement requirement](https://info.arxiv.org/help/endorsement.html).
+4. Prepare the upload and metadata; verify the processed PDF and the selected
+   [arXiv license](https://info.arxiv.org/help/license/index.html). CC BY 4.0 is
+   an available option consistent with the selected article terms.
+5. The author approves the concrete submission and completes the submission
+   agreement. Add the real arXiv URL to the publication index only after it exists.
+
+Official guidance was checked on 2026-09-25; recheck it at submission time.
+The GitHub destination is [inlevel9-com/Vons](https://github.com/inlevel9-com/Vons)
+and the Hugging Face repository is [INLEVEL9/Vons](https://huggingface.co/INLEVEL9/Vons).
+Neither link establishes public artifact availability, replication or acceptance.

docs/publications/LICENSE.md

@@ -0,0 +1,40 @@
+# Article license: CC BY 4.0
+
+The Vons paper and Tech Report, including their original research figures, are
+prepared for release under the **Creative Commons Attribution 4.0 International
+License (CC BY 4.0)**, as selected by the author on 2026-09-24.
+
+Author: Kwangseob Ahn  
+Affiliation: INLEVEL9 / SEJONG UNIV.  
+Contact: oswarld@inlevel9.com
+
+The [CC BY 4.0 legal code](https://creativecommons.org/licenses/by/4.0/legalcode.en)
+governs the article material identified by this notice. The
+[license summary](https://creativecommons.org/licenses/by/4.0/) explains sharing,
+adaptation and attribution. Commercial reuse of the articles is permitted under
+CC BY 4.0; the software's commercial-use restriction does not apply to them.
+
+Retain the author, title, version, license link and supplied attribution notices;
+indicate modifications. Do not imply the author's or institutions' endorsement.
+Third-party material specifically identified under other terms, software source
+excerpts identified as separately licensed, logos, raw benchmark data and private
+verification records are excluded from this article grant. Statutory exceptions
+and independent rights remain unaffected.
+
+This notice does not license the Vons software or any model weights. See the
+repository's [software license](../../LICENSE) for software use. It does not
+claim that an article has been submitted, accepted, externally peer-reviewed or
+already uploaded to a public destination.
+
+## Notice for the v0.2 release copies
+
+This notice records the author's decision after the research evidence was
+frozen. It applies to the selected release copies of the Vons paper v0.2 and
+Technical Report v0.2 and their original figures. Where an earlier manuscript
+states that article terms await an owner decision, this notice supersedes that
+article-license status only. It does not alter measurements, claim provenance,
+publication status, or the remaining research gates.
+
+Distribute this notice alongside the reviewed manuscript files and their
+release checksums. The Tech Report's original author/model attribution is
+preserved; a separate licensing notice does not replace its authoring history.

docs/publications/README.md

@@ -0,0 +1,40 @@
+# Paper and Tech Report
+
+The reviewed PDFs are included in this release. Both files preserve the final
+manuscript bytes; publication does not imply new experiments or peer acceptance.
+
+Author: **Kwangseob Ahn**  
+Affiliation: **INLEVEL9 / SEJONG UNIV.**  
+Contact: **oswarld@inlevel9.com**
+
+| Publication | Version | Download |
+| --- | --- | --- |
+| Vons: A Compact, Host-Controlled Decision Component for Agent Workflows | Paper v1.0, final editorial revision | [PDF · 15 pages](vons-paper-v1.0.pdf) |
+| Vons: Compact Decision Models for Frontier-Agent Workflows | Technical Report v1.0.1 | [PDF · 20 pages](vons-tech-report-v1.0.1.pdf) |
+
+## Verification and provenance
+
+The final documents were reviewed against the frozen evidence packet and primary
+references, including tables, figures, negative results and missing measurements.
+Every PDF page was visually inspected. Independently checked local SHA-256
+values match the reviewed final versions. All pages render as US Letter, fonts
+are embedded, and no PDF JavaScript, launch action or embedded attachment was
+found. These are genuine Typst-generated PDFs; a clean source rebuild has not
+been independently completed and is not claimed.
+
+| File | SHA-256 |
+| --- | --- |
+| `vons-paper-v1.0.pdf` | `ae0e09c60e17a98b52bb25c611b2489d10b18bd98d87974f2e8dd25d746a5fc8` |
+| `vons-tech-report-v1.0.1.pdf` | `33076d9e52d4a073060066215dd390e3b0bf0cdef48c5ffb2a7c5189854254ed` |
+
+Only these exact PDFs are permitted by the public allowlist. Drafts, prompts,
+claim ledgers, review conversations, source bundles and restricted benchmark data
+remain excluded. The software has its own version, **0.1.0 research preview**.
+
+The [CC BY 4.0 article license](LICENSE.md) covers both manuscripts and their
+original figures. Software rights are governed separately by the
+[Vons Community and Commercial License 1.0](../../LICENSE); article licensing
+does not grant commercial software rights.
+
+arXiv submission is in preparation. No arXiv identifier, DOI or acceptance is
+announced. See the [arXiv preparation checklist](ARXIV.md).

pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vons"
+version = "0.1.0"
+description = "Small local decision models for frontier-agent workflows"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "LicenseRef-Vons-Community-Commercial-1.0"
+license-files = ["LICENSE"]
+authors = [{ name = "Vons contributors" }]
+dependencies = []
+
+[project.optional-dependencies]
+train = ["numpy>=1.26", "torch>=2.2", "transformers>=4.40", "safetensors>=0.4"]
+export = ["onnx>=1.16", "onnxruntime>=1.18", "onnxscript>=0.5"]
+ollama = ["ollama>=0.3"]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[project.scripts]
+vons = "vons.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["vons*"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+# Preserve acquired upstream evidence byte-for-byte; it is not Vons source.
+extend-exclude = ["data/restricted"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sdk/typescript/LICENSE

@@ -0,0 +1,104 @@
+Vons Community and Commercial License 1.0
+SPDX-License-Identifier: LicenseRef-Vons-Community-Commercial-1.0
+
+1. Scope and definitions
+
+"Licensor" means each copyright holder who makes material available under this
+license. "Software" means the Vons-owned source code, configuration, tests and
+supporting software documentation accompanied by this license, including copies
+and modifications. "You" means the individual or legal entity exercising the
+permissions below, including persons acting on that entity's behalf.
+
+This license does not cover material with a separate license notice. In
+particular, the paper and Tech Report and their original research figures are
+licensed separately under CC BY 4.0. Third-party dependencies, upstream model
+assets, datasets, trademarks and logos are not relicensed by this document.
+No model weights or benchmark datasets are supplied with this source release.
+
+"Noncommercial Use" means personal learning, independent noncommercial
+research, or noncommercial education, research or public-benefit activity by a
+nonprofit or educational institution, where the activity is not undertaken for
+commercial advantage, monetary compensation, or on behalf of a business.
+Nonprofit or educational status alone does not make commercial activity
+Noncommercial Use. Unrestricted donations that do not buy a service or benefit
+do not by themselves make an otherwise qualifying activity commercial.
+
+"Commercial Use" includes paid consulting or client work; use in or to support
+a monetized product, service, SaaS, API, hosted or managed service; internal
+business operations; and evaluation, research or deployment by, for, or on
+behalf of a for-profit enterprise. Contractors and affiliates acting for such
+an enterprise require the same permission. Personal use by an employee outside
+their employment, without business benefit, may qualify as Noncommercial Use.
+
+2. Free community permission
+
+Subject to this license, each Licensor grants You a worldwide, nonexclusive,
+royalty-free copyright license to use, reproduce, study, modify, display and
+distribute the Software solely for Noncommercial Use. You may provide access
+to an otherwise qualifying noncommercial service under these conditions.
+Only rights that a Licensor is entitled to grant are included.
+
+3. Redistribution and attribution
+
+When distributing copies or substantial portions of the Software, including
+modified copies or a compiled form, You must:
+
+(a) retain this license, copyright notices and attribution notices;
+(b) clearly identify Your modifications and preserve their provenance;
+(c) identify the Vons version or source revision used where available; and
+(d) convey these same use restrictions for the covered Software, without
+    representing that You can grant Commercial Use rights.
+
+Do not remove notices, misrepresent origin, or imply endorsement by a Licensor,
+INLEVEL9, Sejong University or any other named institution. For research that
+uses Vons, include an appropriate citation to the software and relevant paper
+or Tech Report when reporting results. An unavailable DOI is not required.
+Attribution or citation does not authorize an otherwise restricted use.
+
+4. Enterprise and commercial permission
+
+Commercial Use is not granted by this license. It requires a separate written
+commercial agreement from the relevant Licensor before the activity begins.
+There is no automatic enterprise evaluation or free-trial exception. Contact
+oswarld@inlevel9.com to arrange the scope, fees and permitted entities.
+This license sets no price, billing unit, service level or support commitment.
+A commercial agreement applies only to the parties and scope it identifies.
+
+5. Outputs and independent rights
+
+This license claims no ownership or royalty over Your inference outputs merely
+because they were produced using the Software. Outputs do not authorize an
+unlicensed deployment and may contain material subject to independent rights.
+Your inputs remain subject to their own rights and permissions.
+
+No trademark, logo, certification or endorsement rights are granted, except
+the descriptive use needed to comply with the notices above. No patent license
+is granted by this document. Statutory exceptions and other independently
+obtained permissions are unaffected. This license does not revoke rights
+previously granted under another license for an earlier copy, and does not
+restrict separately licensed third-party components.
+
+6. Termination and cure
+
+Your permissions terminate automatically if You materially breach this
+license. They are reinstated when the breach is cured within 30 days after
+You first discover it, provided this is Your first breach. Otherwise written
+reinstatement from the relevant Licensor is required. Termination does not
+affect compliant recipients' direct permissions or obligations that by their
+nature survive, including the notices and disclaimers below.
+
+7. Warranty disclaimer and liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THE SOFTWARE IS PROVIDED
+"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND
+NONINFRINGEMENT. THE LICENSORS ARE NOT LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY ARISING FROM THE SOFTWARE OR ITS USE, WHETHER IN CONTRACT, TORT OR
+OTHERWISE. NOTHING HERE EXCLUDES LIABILITY THAT CANNOT LAWFULLY BE EXCLUDED.
+
+8. General
+
+Rights not expressly granted are reserved. No later license version applies
+automatically. If a provision is unenforceable, the remaining provisions remain
+in effect to the extent permitted by law. This is a source-available license
+with use restrictions; it is not an OSI-approved open-source license.

sdk/typescript/README.md

@@ -0,0 +1,49 @@
+# `@vons/decision-sdk`
+
+The TypeScript package mirrors the Vons Python request/response contract and
+keeps KASI policy and execution in the host. It contains no tool executor and
+does not treat a model-produced risk or confidence value as permission.
+
+The contract-only entry point remains small, while the optional `./onnx`
+subpath uses pinned `onnxruntime-web@1.30.0` and
+`@huggingface/tokenizers@0.2.0` for local browser inference. Applications
+provide a model backend through `DecisionBackend`; the runtime helper verifies
+bundle bytes, uses the declared WASM or WebGPU provider, and does not silently
+fall back from an unavailable accelerator.
+`callFingerprint` returns a canonical JSON consent key. Hosts that persist
+consent for the Python adapter should SHA-256 this key before storage so the
+cross-language fingerprint format remains identical.
+
+Node 22+ can load the source directly with its TypeScript type stripping during
+early development. A release build should type-check and bundle the package
+with the consuming application's toolchain.
+
+The local smoke harness covers both pilot bundles and both providers. Build it
+and serve the repository root so the browser can fetch the ignored ORT runtime
+files and the existing pilot artifacts:
+
+```sh
+npm ci
+npm run build:browser
+cd ../..
+python3 -m http.server 8765 --bind 127.0.0.1
+```
+
+Open `http://127.0.0.1:8765/sdk/typescript/demo/`. The smoke page reports
+session-load and one-request timings, optional Chromium JS-heap observations,
+provider evidence, and the contract response. These are diagnostic smoke
+values, not the repeated benchmark protocol.
+
+## Source preview
+
+This package is private in npm metadata until an npm release is requested.
+Its `files` allowlist includes source, this guide and the software license. Models, tokenizers,
+datasets, generated demo JavaScript and dependencies are intentionally excluded
+from the public source export. Build the demos locally and supply your own
+reviewed model bundles before opening the smoke, benchmark or parity pages.
+
+The [Vons Community and Commercial License 1.0](LICENSE) permits qualifying
+noncommercial use without a fee. Enterprise and other commercial use require a
+separate written agreement; contact oswarld@inlevel9.com. This is source-available
+software. Dependencies retain their own terms, and the research articles' CC BY
+4.0 license does not grant commercial SDK rights.

sdk/typescript/demo/benchmark.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Vons ONNX Runtime Web benchmark</title>
+  </head>
+  <body>
+    <main>
+      <h1>Vons ONNX Runtime Web benchmark</h1>
+      <p>Run with query parameters such as <code>?backend=direct&amp;provider=wasm&amp;sessions=5&amp;warmup=10&amp;repeats=100</code>.</p>
+      <button id="download-report" type="button" hidden>Download raw report</button>
+      <pre id="output">Waiting for benchmark parameters.</pre>
+    </main>
+    <script type="module" src="./benchmark.js"></script>
+  </body>
+</html>

sdk/typescript/demo/benchmark.ts

@@ -0,0 +1,285 @@
+import { createOnnxWebBackend, type OnnxTimingSample } from "../src/onnx.ts";
+
+type BackendName = "direct" | "diffusion";
+type ProviderName = "wasm" | "webgpu";
+
+interface PerformanceWithMemory extends Performance {
+  memory?: { usedJSHeapSize: number };
+}
+
+interface NavigatorWithDeviceMemory extends Navigator {
+  deviceMemory?: number;
+}
+
+interface BenchmarkSample extends Omit<OnnxTimingSample, "live_candidates" | "allocated_candidates" | "live_tokens" | "sequence_length" | "tokenizeMs" | "prepareFeedMs" | "inferenceAndReadbackMs" | "postprocessMs" | "totalRequestMs"> {
+  run_id: string;
+  session_start: number;
+  repeat: number;
+  case_id: string;
+  backend: BackendName;
+  requested_provider: ProviderName;
+  observed_provider: ProviderName | null;
+  observed_provider_status: string;
+  live_candidates: number | null;
+  allocated_candidates: number | null;
+  live_tokens: number | null;
+  sequence_length: number | null;
+  tokenizeMs: number | null;
+  prepareFeedMs: number | null;
+  inferenceAndReadbackMs: number | null;
+  postprocessMs: number | null;
+  totalRequestMs: number | null;
+  bundle_hash: string | null;
+  tokenizer_hash: string | null;
+  input_hash: string;
+  noise_hash: string | null;
+  js_heap_used_bytes_before: number | null;
+  js_heap_used_bytes_after: number | null;
+  status: "ok" | "error";
+  error_kind?: string;
+}
+
+interface SessionRecord {
+  session_start: number;
+  load_ms: number;
+  status: "ok" | "error";
+  error_kind?: string;
+}
+
+const output = document.querySelector<HTMLElement>("#output");
+if (!output) throw new Error("benchmark output is missing");
+const downloadButton = document.querySelector<HTMLButtonElement>("#download-report");
+if (!downloadButton) throw new Error("benchmark download button is missing");
+
+function showReport(report: unknown, fileName: string): void {
+  const text = JSON.stringify(report, null, 2);
+  output.textContent = text;
+  downloadButton.hidden = false;
+  downloadButton.onclick = () => {
+    const blob = new Blob([text], { type: "application/json" });
+    const url = URL.createObjectURL(blob);
+    const anchor = document.createElement("a");
+    anchor.href = url;
+    anchor.download = fileName;
+    anchor.click();
+    URL.revokeObjectURL(url);
+  };
+  console.log(text);
+}
+
+const manifestUrls = {
+  direct: new URL("../../../artifacts/pilot/bundle-manifest-v1.json", import.meta.url),
+  diffusion: new URL("../../../artifacts/pilot-diffusion/bundle-manifest-v1.json", import.meta.url),
+};
+
+const manifestHashes = {
+  direct: "bd39eea2b8d5ed5f4d57daefdd4822c4e2c4817a68c4a42bef850b5edcbc97d",
+  diffusion: "df0e7cae640c6604fb517a88d08dbdaa2454d6b3dbbf5708926349cf490b9607",
+};
+
+const heapBytes = (): number | null => (performance as PerformanceWithMemory).memory?.usedJSHeapSize ?? null;
+
+function parameter(name: string, fallback: number): number {
+  const raw = new URLSearchParams(location.search).get(name);
+  if (raw === null) return fallback;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 1) throw new RangeError(`${name} must be a positive integer`);
+  return value;
+}
+
+function textParameter(name: string, fallback: string): string {
+  return new URLSearchParams(location.search).get(name) ?? fallback;
+}
+
+function stableJson(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b));
+  return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(",")}}`;
+}
+
+async function sha256(value: string | ArrayBufferLike): Promise<string> {
+  const bytes = typeof value === "string" ? new TextEncoder().encode(value) : new Uint8Array(value);
+  const digest = await crypto.subtle.digest("SHA-256", bytes as unknown as BufferSource);
+  return Array.from(new Uint8Array(digest), (item) => item.toString(16).padStart(2, "0")).join("");
+}
+
+// Frozen from NumPy default_rng(7).standard_normal((1, 32), dtype=float32).
+// The array, rather than a language-specific seed algorithm, is the parity input.
+const FROZEN_NOISE_SEED_7 = Float32Array.from([
+  1.52196932, -1.14410579, 1.15016162, -1.78465319, -0.77149874, 1.01916146,
+  -0.926134586, -0.415745318, -0.0629121512, 0.513251185, -0.285995334,
+  1.98480856, 1.30306911, -0.00464721443, 1.17548203, 1.34566987,
+  -0.171809882, -2.4133966, -0.0993812904, -0.979565322, 0.942675471,
+  0.452982962, 0.53610903, 0.494613141, 1.94684041, 0.207542002,
+  -1.64390635, -0.542155981, -0.384397745, -0.410856962, 0.946411192,
+  0.979099393,
+]);
+
+function percentile(values: number[], fraction: number): number | null {
+  if (values.length === 0) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  const index = (sorted.length - 1) * fraction;
+  const lower = Math.floor(index);
+  const upper = Math.ceil(index);
+  if (lower === upper) return sorted[lower];
+  return sorted[lower] + (sorted[upper] - sorted[lower]) * (index - lower);
+}
+
+async function run(): Promise<void> {
+  const backendName = textParameter("backend", "direct") as BackendName;
+  const provider = textParameter("provider", "wasm") as ProviderName;
+  if (!(["direct", "diffusion"] as string[]).includes(backendName)) throw new RangeError("backend must be direct or diffusion");
+  if (!(["wasm", "webgpu"] as string[]).includes(provider)) throw new RangeError("provider must be wasm or webgpu");
+  const sessions = parameter("sessions", 1);
+  const warmup = parameter("warmup", 1);
+  const repeats = parameter("repeats", 3);
+  const caseCount = parameter("cases", 20);
+  const runId = crypto.randomUUID();
+  const cases = Array.from({ length: caseCount }, (_, index) => ({
+    caseId: `case-${index + 1}`,
+    state: `browser benchmark state ${index + 1}`,
+  }));
+  const request = (caseIndex: number) => ({
+    state: cases[caseIndex % cases.length].state,
+    questions: [{ id: cases[caseIndex % cases.length].caseId, type: "choice" as const, prompt: "Choose the next action", options: ["continue", "stop", "inspect", "defer"] }],
+    seed: 7,
+  });
+  const inputHashes = new Map(cases.map((item, index) => [item.caseId, stableJson(request(index))]));
+  const hashedInputs = new Map<string, string>();
+  for (const [caseId, value] of inputHashes) hashedInputs.set(caseId, await sha256(value));
+  const noise = backendName === "diffusion" ? FROZEN_NOISE_SEED_7 : null;
+  const noiseHash = noise ? await sha256(noise.buffer) : null;
+  const browserEnvironment = {
+    user_agent: navigator.userAgent,
+    platform: navigator.platform || null,
+    hardware_concurrency: navigator.hardwareConcurrency ?? null,
+    device_memory_gb: (navigator as NavigatorWithDeviceMemory).deviceMemory ?? null,
+    cross_origin_isolated: globalThis.crossOriginIsolated,
+  };
+  const samples: BenchmarkSample[] = [];
+  const sessionRecords: SessionRecord[] = [];
+  let runtimeInfo: Awaited<ReturnType<typeof createOnnxWebBackend>>["runtimeInfo"] | null = null;
+
+  for (let sessionStart = 1; sessionStart <= sessions; sessionStart += 1) {
+    let timing: OnnxTimingSample | undefined;
+    const started = performance.now();
+    let backend: Awaited<ReturnType<typeof createOnnxWebBackend>> | undefined;
+    try {
+      backend = await createOnnxWebBackend({
+        manifestUrl: manifestUrls[backendName],
+        expectedManifestSha256: manifestHashes[backendName],
+        provider,
+        wasmPaths: "/sdk/typescript/node_modules/onnxruntime-web/dist/",
+        wasmNumThreads: 1,
+        onTiming: (sample) => { timing = sample; },
+        initialNoise: backendName === "diffusion" ? () => new Float32Array(noise as Float32Array) : undefined,
+      });
+      runtimeInfo = backend.runtimeInfo;
+      sessionRecords.push({ session_start: sessionStart, load_ms: performance.now() - started, status: "ok" });
+      for (let repeat = 0; repeat < warmup; repeat += 1) await backend.decide(request(repeat));
+      for (let repeat = 0; repeat < repeats; repeat += 1) {
+        const caseValue = cases[repeat % cases.length];
+        const before = heapBytes();
+        timing = undefined;
+        try {
+          await backend.decide(request(repeat));
+          if (!timing) throw new Error("timing hook did not produce a sample");
+          samples.push({
+            ...timing,
+            run_id: runId,
+            session_start: sessionStart,
+            repeat,
+            case_id: caseValue.caseId,
+            backend: backendName,
+            requested_provider: provider,
+            observed_provider: null,
+            observed_provider_status: "session_created; execution_partition_not_exposed",
+            live_candidates: timing.live_candidates,
+            allocated_candidates: timing.allocated_candidates,
+            live_tokens: timing.live_tokens,
+            sequence_length: timing.sequence_length,
+            bundle_hash: backend.manifestHash,
+            tokenizer_hash: backend.manifest.files.find((item) => item.path.endsWith("tokenizer.json"))?.sha256 ?? null,
+            input_hash: hashedInputs.get(caseValue.caseId) as string,
+            noise_hash: noiseHash,
+            js_heap_used_bytes_before: before,
+            js_heap_used_bytes_after: heapBytes(),
+            status: "ok",
+          });
+        } catch (error) {
+          samples.push({
+            questionId: caseValue.caseId,
+            tokenizeMs: null,
+            prepareFeedMs: null,
+            inferenceAndReadbackMs: null,
+            postprocessMs: null,
+            totalRequestMs: null,
+            run_id: runId,
+            session_start: sessionStart,
+            repeat,
+            case_id: caseValue.caseId,
+            backend: backendName,
+            requested_provider: provider,
+            observed_provider: null,
+            observed_provider_status: "request_failed; execution_partition_not_exposed",
+            live_candidates: null,
+            allocated_candidates: null,
+            live_tokens: null,
+            sequence_length: null,
+            bundle_hash: backend.manifestHash,
+            tokenizer_hash: backend.manifest.files.find((item) => item.path.endsWith("tokenizer.json"))?.sha256 ?? null,
+            input_hash: hashedInputs.get(caseValue.caseId) as string,
+            noise_hash: noiseHash,
+            js_heap_used_bytes_before: before,
+            js_heap_used_bytes_after: heapBytes(),
+            status: "error",
+            error_kind: error instanceof Error ? `${error.name}: ${error.message}` : String(error),
+          });
+        }
+      }
+    } catch (error) {
+      sessionRecords.push({ session_start: sessionStart, load_ms: performance.now() - started, status: "error", error_kind: error instanceof Error ? `${error.name}: ${error.message}` : String(error) });
+    } finally {
+      await backend?.dispose();
+    }
+  }
+
+  const successful = samples.filter((sample) => sample.status === "ok");
+  const memoryMaximum = (values: Array<number | null>): number | null => {
+    const available = values.filter((value): value is number => value !== null);
+    return available.length === 0 ? null : Math.max(...available);
+  };
+  const report = {
+    schema: "vons.browser-benchmark/v1",
+    run_id: runId,
+    backend: backendName,
+    requested_provider: provider,
+    sessions,
+    warmup_excluded_per_session: warmup,
+    repeats_per_session: repeats,
+    cases: caseCount,
+    environment: browserEnvironment,
+    runtime_info: runtimeInfo,
+    session_start_semantics: "new ORT session on one page; module and browser caches may persist",
+    execution_provider_evidence: "requested provider and session creation only; graph partition status is not exposed by this harness",
+    session_records: sessionRecords,
+    samples,
+    summary: {
+      successful_samples: successful.length,
+      failed_samples: samples.length - successful.length,
+      total_request_ms_p50: percentile(successful.flatMap((sample) => sample.totalRequestMs === null ? [] : [sample.totalRequestMs]), 0.5),
+      total_request_ms_p95: percentile(successful.flatMap((sample) => sample.totalRequestMs === null ? [] : [sample.totalRequestMs]), 0.95),
+      inference_and_readback_ms_p50: percentile(successful.flatMap((sample) => sample.inferenceAndReadbackMs === null ? [] : [sample.inferenceAndReadbackMs]), 0.5),
+      inference_and_readback_ms_p95: percentile(successful.flatMap((sample) => sample.inferenceAndReadbackMs === null ? [] : [sample.inferenceAndReadbackMs]), 0.95),
+      js_heap_before_max: memoryMaximum(successful.map((sample) => sample.js_heap_used_bytes_before)),
+      js_heap_after_max: memoryMaximum(successful.map((sample) => sample.js_heap_used_bytes_after)),
+      memory_note: "performance.memory before/after observations only; not a peak or GPU-memory measurement",
+    },
+  };
+  showReport(report, `vons-${backendName}-${provider}-${runId}.json`);
+}
+
+void run().catch((error) => {
+  showReport({ schema: "vons.browser-benchmark/v1", status: "error", error: error instanceof Error ? `${error.name}: ${error.message}` : String(error) }, `vons-browser-benchmark-error-${crypto.randomUUID()}.json`);
+});

sdk/typescript/demo/index.html

@@ -0,0 +1,20 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Vons ONNX Runtime Web smoke</title>
+  </head>
+  <body>
+    <main>
+      <h1>Vons ONNX Runtime Web smoke</h1>
+      <p>This harness is intentionally local-only. It reports runtime evidence; it is not a benchmark.</p>
+      <button data-backend="direct">Run Direct / WASM</button>
+      <button data-backend="diffusion">Run Diffusion / WASM</button>
+      <button data-backend="direct-webgpu">Try Direct / WebGPU</button>
+      <button data-backend="diffusion-webgpu">Try Diffusion / WebGPU</button>
+      <pre id="output">Not run.</pre>
+    </main>
+    <script type="module" src="./main.js"></script>
+  </body>
+</html>

sdk/typescript/demo/main.ts

@@ -0,0 +1,78 @@
+import { createOnnxWebBackend } from "../src/onnx.ts";
+
+const outputElement = document.querySelector<HTMLElement>("#output");
+if (!outputElement) throw new Error("smoke output element is missing");
+const output = outputElement;
+
+interface PerformanceWithMemory extends Performance {
+  memory?: { usedJSHeapSize: number };
+}
+
+const heapBytes = (): number | null => (performance as PerformanceWithMemory).memory?.usedJSHeapSize ?? null;
+
+const manifestUrls = {
+  direct: new URL("../../../artifacts/pilot/bundle-manifest-v1.json", import.meta.url),
+  diffusion: new URL("../../../artifacts/pilot-diffusion/bundle-manifest-v1.json", import.meta.url),
+};
+
+const manifestHashes = {
+  direct: "bd39eea2b8d5ed5f4d57daefdd4822c4e2c4817a68c4a42bef850b5edcbc97d",
+  diffusion: "df0e7cae640c6604fb517a88d08dbdaa2454d6b3dbbf5708926349cf490b9607",
+};
+
+function show(value: unknown): void {
+  output.textContent = typeof value === "string" ? value : JSON.stringify(value, null, 2);
+}
+
+async function run(provider: "wasm" | "webgpu", backendName: "direct" | "diffusion"): Promise<void> {
+  const started = performance.now();
+  let backend: Awaited<ReturnType<typeof createOnnxWebBackend>> | undefined;
+  try {
+    backend = await createOnnxWebBackend({
+      manifestUrl: manifestUrls[backendName],
+      expectedManifestSha256: manifestHashes[backendName],
+      provider,
+      wasmPaths: "/sdk/typescript/node_modules/onnxruntime-web/dist/",
+      wasmNumThreads: 1,
+    });
+    const initialized = performance.now();
+    const beforeMemory = heapBytes();
+    const response = await backend.decide({
+      state: "browser smoke state",
+      questions: [{ id: "smoke", type: "choice", prompt: "Choose the next action", options: ["continue", "stop"] }],
+      seed: 7,
+    });
+    const completed = performance.now();
+    show({
+      pass: true,
+      backend: backendName,
+      runtime: backend.runtimeInfo,
+      load_ms: initialized - started,
+      inference_ms: completed - initialized,
+      total_ms: completed - started,
+      js_heap_used_bytes_before: beforeMemory,
+      js_heap_used_bytes_after: heapBytes(),
+      response,
+    });
+  } catch (error) {
+    show({
+      pass: false,
+      backend: backendName,
+      provider,
+      elapsed_ms: performance.now() - started,
+      error: error instanceof Error ? `${error.name}: ${error.message}` : String(error),
+    });
+  } finally {
+    await backend?.dispose();
+  }
+}
+
+for (const button of Array.from(document.querySelectorAll<HTMLButtonElement>("button[data-backend]"))) {
+  button.addEventListener("click", () => {
+    const value = button.dataset.backend;
+    if (value === "direct") void run("wasm", "direct");
+    else if (value === "diffusion") void run("wasm", "diffusion");
+    else if (value === "direct-webgpu") void run("webgpu", "direct");
+    else if (value === "diffusion-webgpu") void run("webgpu", "diffusion");
+  });
+}

sdk/typescript/demo/parity.html

@@ -0,0 +1,20 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Vons ONNX Runtime Web parity matrix</title>
+  </head>
+  <body>
+    <main>
+      <h1>Vons ONNX Runtime Web parity matrix</h1>
+      <p>This local harness runs the frozen 23-fixture contract matrix. It is not a quality benchmark.</p>
+      <button id="run">Run selected backend/provider</button>
+      <button id="download" disabled>Download report</button>
+      <label>Backend <select id="backend"><option value="direct">Direct</option><option value="diffusion">Diffusion</option></select></label>
+      <label>Provider <select id="provider"><option value="wasm">WASM</option><option value="webgpu">WebGPU</option></select></label>
+      <pre id="output">Not run.</pre>
+    </main>
+    <script type="module" src="./parity.js"></script>
+  </body>
+</html>

sdk/typescript/demo/parity.ts

@@ -0,0 +1,239 @@
+import { createOnnxWebBackend, type OnnxTimingSample, type OnnxTraceSample } from "../src/onnx.ts";
+import type { DecisionRequest, DecisionResponse, QuestionType } from "../src/index.ts";
+
+export type ParityBackend = "direct" | "diffusion";
+export type ParityProvider = "wasm" | "webgpu";
+
+export interface ParityFixture {
+  id: string;
+  request: DecisionRequest;
+  expectedFailure?: string;
+  matrix: { candidate_count: number; family: string; target_tokens: string };
+}
+
+export interface ParityRecord {
+  fixture_id: string;
+  input_hash: string;
+  request: DecisionRequest;
+  matrix: ParityFixture["matrix"];
+  status: "ok" | "expected_error" | "unexpected_error";
+  response?: DecisionResponse;
+  timings?: OnnxTimingSample[];
+  traces?: OnnxTraceSample[];
+  error?: string;
+}
+
+const manifestUrls: Record<ParityBackend, URL> = {
+  direct: new URL("../../../artifacts/pilot/bundle-manifest-v1.json", import.meta.url),
+  diffusion: new URL("../../../artifacts/pilot-diffusion/bundle-manifest-v1.json", import.meta.url),
+};
+
+const manifestHashes: Record<ParityBackend, string> = {
+  direct: "bd39eea2b8d5ed5f4d57daefdd4822c4e2c4817a68c4a42bef850b5edcbc97d",
+  diffusion: "df0e7cae640c6604fb517a88d08dbdaa2454d6b3dbbf5708926349cf490b9607",
+};
+
+const FROZEN_NOISE_SEED_7 = Float32Array.from([
+  1.52196932, -1.14410579, 1.15016162, -1.78465319, -0.77149874, 1.01916146,
+  -0.926134586, -0.415745318, -0.0629121512, 0.513251185, -0.285995334, 1.98480856,
+  1.30306911, -0.00464721443, 1.17548203, 1.34566987, -0.171809882, -2.4133966,
+  -0.0993812904, -0.979565322, 0.942675471, 0.452982962, 0.53610903, 0.494613141,
+  1.94684041, 0.207542002, -1.64390635, -0.542155981, -0.384397745, -0.410856962,
+  0.946411192, 0.979099393,
+]);
+
+function options(count: number, label: string): string[] {
+  return Array.from({ length: count }, (_, index) => `${label} candidate ${index + 1}`);
+}
+
+function question(
+  id: string,
+  type: QuestionType,
+  prompt: string,
+  values: string[],
+): DecisionRequest["questions"][number] {
+  return type === "score"
+    ? { id, type, prompt, options: values, rubric: ["poor", "fair", "good", "very good", "excellent"] }
+    : { id, type, prompt, options: values };
+}
+
+function fixture(
+  id: string,
+  family: string,
+  targetTokens: string,
+  candidateCount: number,
+  state: DecisionRequest["state"],
+  item: DecisionRequest["questions"][number],
+  expectedFailure?: string,
+): ParityFixture {
+  return {
+    id,
+    request: { state, questions: [item], seed: 7 },
+    expectedFailure,
+    matrix: { candidate_count: candidateCount, family, target_tokens: targetTokens },
+  };
+}
+
+export function buildParityFixtures(): ParityFixture[] {
+  const result: ParityFixture[] = [];
+  const counts = [2, 4, 8, 16, 32];
+  for (const count of counts) {
+    result.push(fixture(`short-${count}`, "choice", "short", count, "ready", question(`short-${count}-q`, "choice", "Choose the next action", options(count, "short"))));
+    result.push(fixture(`unicode-${count}`, "choice", "unicode", count, { locale: "ko-KR", state: `검토 중인 화면 🌐 / пункт ${count}` }, question(`unicode-${count}-q`, "choice", "다음에 선택할 항목은 무엇입니까?", options(count, "unicode/다음"))));
+    result.push(fixture(`score-${count}`, "score", "unsupported", count, { workflow: "quality", count, labels: ["α", "β", "γ"] }, question(`score-${count}-q`, "score", "Rate the candidate outcome", options(count, "score")), "score_head_unsupported"));
+    const repeats = Math.max(2, Math.floor(60 / count));
+    result.push(fixture(`long-${count}`, "choice", "near-aggregate-limit", count, "state ".repeat(50), question(`long-${count}-q`, "choice", "Select the most relevant detailed action", options(count, "detail ".repeat(repeats)))));
+  }
+  result.push(fixture("boolean-2", "boolean", "boolean", 2, "permission check", question("boolean-q", "boolean", "Should the host ask for confirmation?", [])));
+  result.push({
+    id: "multi-question",
+    request: {
+      state: { page: "settings", text: "Review before any external action" },
+      questions: [
+        question("multi-choice", "choice", "Which next step is safest?", options(4, "multi")),
+        question("multi-boolean", "boolean", "Is confirmation required?", []),
+      ],
+      seed: 7,
+    },
+    matrix: { candidate_count: 4, family: "multi-question", target_tokens: "mixed" },
+  });
+  result.push(fixture(
+    "overflow-explicit",
+    "overflow",
+    "over-limit",
+    2,
+    "x ".repeat(700),
+    question("overflow-q", "choice", "This request must fail explicitly", options(2, "overflow")),
+    "request_validation_or_tokenization_overflow",
+  ));
+  return result;
+}
+
+function stableJson(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b));
+  return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(",")}}`;
+}
+
+async function sha256(value: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+  return Array.from(new Uint8Array(digest), (item) => item.toString(16).padStart(2, "0")).join("");
+}
+
+export async function runParityCell(backendName: ParityBackend, provider: ParityProvider): Promise<Record<string, unknown>> {
+  const fixtures = buildParityFixtures();
+  const records: ParityRecord[] = [];
+  let timings: OnnxTimingSample[] = [];
+  let traces: OnnxTraceSample[] = [];
+  const backend = await createOnnxWebBackend({
+    manifestUrl: manifestUrls[backendName],
+    expectedManifestSha256: manifestHashes[backendName],
+    provider,
+    wasmPaths: "/sdk/typescript/node_modules/onnxruntime-web/dist/",
+    wasmNumThreads: 1,
+    initialNoise: backendName === "diffusion" ? () => new Float32Array(FROZEN_NOISE_SEED_7) : undefined,
+    onTiming: (sample) => { timings.push(sample); },
+    onTrace: (sample) => { traces.push(sample); },
+  });
+  try {
+    for (const item of fixtures) {
+      const inputHash = await sha256(stableJson(item.request));
+      timings = [];
+      traces = [];
+      try {
+        const response = await backend.decide(item.request);
+        records.push({ fixture_id: item.id, input_hash: inputHash, request: item.request, matrix: item.matrix, status: "ok", response, timings, traces });
+      } catch (error) {
+        const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+        records.push({
+          fixture_id: item.id,
+          input_hash: inputHash,
+          request: item.request,
+          matrix: item.matrix,
+          status: item.expectedFailure ? "expected_error" : "unexpected_error",
+          timings,
+          traces,
+          error: message,
+        });
+      }
+    }
+  } finally {
+    await backend.dispose();
+  }
+  return {
+    schema: "vons.browser-parity/v1",
+    backend: backendName,
+    requested_provider: provider,
+    fixture_count: fixtures.length,
+    runtime_info: backend.runtimeInfo,
+    manifest_hash: backend.manifestHash,
+    tokenizer_hash: backend.manifest.files.find((item) => item.path.endsWith("tokenizer.json"))?.sha256 ?? null,
+    noise_seed: backendName === "diffusion" ? 7 : null,
+    noise_values: backendName === "diffusion" ? Array.from(FROZEN_NOISE_SEED_7) : null,
+    records,
+    limitations: [
+      "This harness checks contract-valid responses and reproducible fixture inputs; it does not establish task accuracy.",
+      "A browser-vs-Python numeric parity claim requires separately saved CPU reference outputs for the same input and noise hashes.",
+      "WebGPU provider selection does not expose graph partition evidence in this runtime harness.",
+    ],
+  };
+}
+
+if (typeof document !== "undefined") {
+  const runButton = document.querySelector<HTMLButtonElement>("#run");
+  const output = document.querySelector<HTMLElement>("#output");
+  const backendSelect = document.querySelector<HTMLSelectElement>("#backend");
+  const providerSelect = document.querySelector<HTMLSelectElement>("#provider");
+  const downloadButton = document.querySelector<HTMLButtonElement>("#download");
+  if (!runButton || !output || !backendSelect || !providerSelect || !downloadButton) throw new Error("parity harness controls are missing");
+  let lastReport: Record<string, unknown> | null = null;
+  const displayReport = (report: Record<string, unknown>): void => {
+    const records = Array.isArray(report.records) ? report.records as Array<Record<string, unknown>> : [];
+    const statusCounts = records.reduce<Record<string, number>>((counts, record) => {
+      const status = String(record.status ?? "unknown");
+      counts[status] = (counts[status] ?? 0) + 1;
+      return counts;
+    }, {});
+    output.textContent = JSON.stringify({
+      schema: report.schema,
+      backend: report.backend,
+      requested_provider: report.requested_provider,
+      fixture_count: report.fixture_count,
+      manifest_hash: report.manifest_hash,
+      tokenizer_hash: report.tokenizer_hash,
+      noise_seed: report.noise_seed,
+      status_counts: statusCounts,
+      errors: records.filter((record) => record.status !== "ok").map((record) => ({ fixture_id: record.fixture_id, status: record.status, error: record.error })),
+      note: "Full parity JSON, including request hashes, timings, traces, and noise values, is available through Download report.",
+    }, null, 2);
+  };
+  downloadButton.addEventListener("click", () => {
+    if (!lastReport) return;
+    const backend = backendSelect.value as ParityBackend;
+    const provider = providerSelect.value as ParityProvider;
+    const blob = new Blob([JSON.stringify(lastReport, null, 2)], { type: "application/json" });
+    const url = URL.createObjectURL(blob);
+    const link = document.createElement("a");
+    link.href = url;
+    link.download = `vons-parity-${backend}-${provider}.json`;
+    link.click();
+    URL.revokeObjectURL(url);
+  });
+  runButton.addEventListener("click", async () => {
+    runButton.disabled = true;
+    downloadButton.disabled = true;
+    lastReport = null;
+    output.textContent = "Running...";
+    try {
+      const report = await runParityCell(backendSelect.value as ParityBackend, providerSelect.value as ParityProvider);
+      lastReport = report;
+      downloadButton.disabled = false;
+      displayReport(report);
+    } catch (error) {
+      output.textContent = JSON.stringify({ schema: "vons.browser-parity/v1", status: "error", error: String(error) }, null, 2);
+    } finally {
+      runButton.disabled = false;
+    }
+  });
+}

sdk/typescript/package-lock.json

@@ -0,0 +1,652 @@
+{
+  "name": "@vons/decision-sdk",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@vons/decision-sdk",
+      "version": "0.1.0",
+      "dependencies": {
+        "@huggingface/tokenizers": "0.2.0",
+        "onnxruntime-web": "1.30.0"
+      },
+      "devDependencies": {
+        "esbuild": "0.28.2"
+      },
+      "engines": {
+        "node": ">=22"
+      },
+      "license": "SEE LICENSE IN LICENSE"
+    },
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.2.tgz",
+      "integrity": "sha512-XExcO+dvLKvVtNTibSTBej1NCAbaGhWn9Ww1ZPx80qsahhPFe/8jgWP0IchNe0F3HwkU7n8ejhH8bjonqht8mQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.2.tgz",
+      "integrity": "sha512-kXXoiPVVGQcnIYGOeaovwOURpniDBpSq4A03qkQ+BMQqtGG6HYap3xne9C1O1yo4TR3qxlCX5IqqmX6fFo2Lqg==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.2.tgz",
+      "integrity": "sha512-5YfKeeI8qWfBZIX+u2xZC3Zlb3Os/gLS2sbEKM+I4ZOcsWmHS2WLysCcQZDAFRslDUU5Oiq44gf6PYN1vGwG5A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.2.tgz",
+      "integrity": "sha512-O387ite7SzUyCcy3JQX4P4bLtEA7bLLkx+esve5JHnyYfNTxcVpXZo9jhdB0lTKN44gztELTdU7nS8Nr16Fs1Q==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.2.tgz",
+      "integrity": "sha512-n4KqkOQrraxHJcgjM1RvwbigfQKIKJVpM7xp+KsxiyUSrRdIXnt73VhrPAx0fV44hgfmIVKjxMN9J1t5jySVkw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.2.tgz",
+      "integrity": "sha512-uq6suIWYP37qzGddBKPw5QEQPi6HiLGsO7UmkpfyaYNQ3D+rN6w6WfwH+nuqcGXWvawGwxOEroO4YGnFh95azw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.2.tgz",
+      "integrity": "sha512-n+I0BTSRIoy+d6RPKnEVwql5UwBJolytvY4mAOIEJorKlqgPII8ix6slVVrfZ5Tnj7glIZvloylbB/EJPMWEXw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.2.tgz",
+      "integrity": "sha512-78XJTJkvPs0kz2w61301PJjXl4g7q3JqiYMZ/M/yVI73EHBrCRTgkhu9oqG7vPqq+a/yadEW8aD+agKlk5xrmg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.2.tgz",
+      "integrity": "sha512-XlDnu2q5yoqems+xay6wSAcg9DDD7K9RLKZEBOMZm3ckNpJBvOX20tSfby8KfrrhINDyv9V2YVZKY/SpoGJI8w==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.2.tgz",
+      "integrity": "sha512-pW4AC0P3it8c7do9MVM4p51FzHzdM/TZrerurgRcHJ2WTa1VQ1CIq18xncfpBJw4ojkiZZrKW2yIBWBP92j6Ug==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.2.tgz",
+      "integrity": "sha512-CYbnj78HsIeA+DhgUKgFCfvNsTHFhMMrinUrMZpDXJXKN8T3XViTZ/+wtHeVxEWY8ewSzTFN+nRmSwO2tZaLUQ==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.2.tgz",
+      "integrity": "sha512-buwkd8nsph4R+ajRvw0qM5Hja/TXQow3ptzWO2EbG/cqcIkHloRrdlBtQlshyYGTNFvfkfJ5tpPLVkY4DtsPfQ==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.2.tgz",
+      "integrity": "sha512-ZVykbDyk7519VwiNb9Lcj9m8XM6v5V9uKPvrEMkkEedVewf+0itkhahp4HDpgERXhwLRpWFypsGbG/J8s0QjJA==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.2.tgz",
+      "integrity": "sha512-CAXl+Dtd9UUuJd8pKKdwh6MLm3MUMiqMPmhZ3tTSXPqfyQ3vDl6R5hZdZ/kYojK4ofXtdfSv1tFq8XzWx3heNQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.2.tgz",
+      "integrity": "sha512-GeXCej4IQtU1B+QlDV8W/RRvbzI3O/Stss+/bCXv4lZls5WGRtu2a+3JkA3i4qIUlMXpcHebWpF8AkJhATowuA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.2.tgz",
+      "integrity": "sha512-3H1weTYZPxt/WOhByszQZybS9w5lKzUn1FDMsgEChbHWQwHYQQRfBxgCcZvPhjHfKyJjIievvMmEUawJrdY9Dg==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.2.tgz",
+      "integrity": "sha512-4xTZr1FUmSoQW4XIWmit3tzQrUTZM+N3P0XV8xROKYF50XfI7xeO90+1bZvNwxIufQ9hDQVRJH5YhgPVF8A/HQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.2.tgz",
+      "integrity": "sha512-sSATRjPeDBg3pdgHoQfoYBob11Kk1FGa9lui5RIHZCoCkJa9QKlvl3/vKz2usCmYYjs7ymJR/2Nnsqe+Hjt5nw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.2.tgz",
+      "integrity": "sha512-lqnzCV+mM0gIADaKihiCg6ifgfU2L3h5E33rNQBN1Y4MaVGnzryzmvvf7UHxprpQdE8hpqLolJ9Rl+SkIRDpyw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.2.tgz",
+      "integrity": "sha512-AL2qJILH7lNjrDmCQDvdxMfAUIv8KMNZOvrwAQ8i8//ntL9FflhOyMJ8OZSMBb8/AWXe3/5v5S20y3zCoZWKoQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.2.tgz",
+      "integrity": "sha512-QtiuPytchRyC4rwUKhexJdQKvDuZ6hWloi3igqPQNUJCS1/v9EiO3UTOXR6A3FoMo4fnAKbWJdqaIwhOzh8qEw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.2.tgz",
+      "integrity": "sha512-WkhYDmpTjLvGlScA1rwjRUmhl4k8oXR3cIbtqWmELgU/dFeHHlEllxDvdWcNJV9rbzCexB5vz8gtNewWLgCT7Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.2.tgz",
+      "integrity": "sha512-GPMSkTOtMnv2U2F8gxe4Io6qmVs+YKyp832Etqqxr0hFngmXQ3rzwytelm3GIn7T4VviRUlf3sOgBOiTdvaf7g==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.2.tgz",
+      "integrity": "sha512-PIhhEkE9uPBleRBrQEJpUn7MBnibZzbGzYWPmY3x+YoVg/95zbjB4CxPPOQ8l5tYYM4mMaCthF8/1DIfBQQyWQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.2.tgz",
+      "integrity": "sha512-YmJbfTlvU7Sdn9BB+4PRES4oB6pxgS37MAONj+hBr/cpXS1aBPKXxNnDbu+QCWPj0o9dgyxeq79g6c5P8KeuYA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.2.tgz",
+      "integrity": "sha512-5ebpxr3nWMzrL/rnUI755Jkuee0bHL/Gq0WTF9lvcpv73wAp5eu8MfBUgWK9bhWvZjj7yX8etf/8tI8Ney695g==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@huggingface/tokenizers": {
+      "version": "0.2.0",
+      "resolved": "https://registry.npmjs.org/@huggingface/tokenizers/-/tokenizers-0.2.0.tgz",
+      "integrity": "sha512-LidMHe1FpcSYH4vcSjXooda34pC0M8m1gmDOv7SQi6Iv+ib1zX7J3sHBCC9/3FPCkn2k1b55FneVqMRxrr99pg==",
+      "license": "Apache-2.0"
+    },
+    "node_modules/@protobufjs/aspromise": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/@protobufjs/aspromise/-/aspromise-1.1.2.tgz",
+      "integrity": "sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/base64": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/@protobufjs/base64/-/base64-1.1.2.tgz",
+      "integrity": "sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/codegen": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/@protobufjs/codegen/-/codegen-2.0.5.tgz",
+      "integrity": "sha512-zgXFLzW3Ap33e6d0Wlj4MGIm6Ce8O89n/apUaGNB/jx+hw+ruWEp7EwGUshdLKVRCxZW12fp9r40E1mQrf/34g==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/eventemitter": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/@protobufjs/eventemitter/-/eventemitter-1.1.1.tgz",
+      "integrity": "sha512-vW1GmwMZNnL+gMRaovlh9yZX74kc+TTU3FObkkurpMaRtBfLP3ldjS9KQWlwZgraRE0+dheEEoAxdzcJQ8eXZg==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/fetch": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/@protobufjs/fetch/-/fetch-1.1.1.tgz",
+      "integrity": "sha512-GpptLrs57adMSuHi3VNj0mAF8dwh36LMaYF6XyJ6JMWlVsc+t42tm1HSEDmOs3A8fC9yyeisgLhsTVQokOZ0zw==",
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "@protobufjs/aspromise": "^1.1.1"
+      }
+    },
+    "node_modules/@protobufjs/float": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/@protobufjs/float/-/float-1.0.2.tgz",
+      "integrity": "sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/path": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/@protobufjs/path/-/path-1.1.2.tgz",
+      "integrity": "sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/pool": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@protobufjs/pool/-/pool-1.1.0.tgz",
+      "integrity": "sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@protobufjs/utf8": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/@protobufjs/utf8/-/utf8-1.1.2.tgz",
+      "integrity": "sha512-b1UQwcEZ4yCnMCD8DAL1VlbvBJE9/IX4FTIp7BG1xYpf29SLazLSrqUkj4w7Y5y7cCVP6E5tcqqcI0xemPkHug==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@types/node": {
+      "version": "26.6.2",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-26.6.2.tgz",
+      "integrity": "sha512-X1P21scMv4zGKLYqjdGjaKa7COa0RKVYYZZN/NfvLQ1JegxFhdhpZG/Lyn8AXx6CDUavKAd11v6BvfpkDByK8g==",
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~8.9.0"
+      }
+    },
+    "node_modules/esbuild": {
+      "version": "0.28.2",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.2.tgz",
+      "integrity": "sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.28.2",
+        "@esbuild/android-arm": "0.28.2",
+        "@esbuild/android-arm64": "0.28.2",
+        "@esbuild/android-x64": "0.28.2",
+        "@esbuild/darwin-arm64": "0.28.2",
+        "@esbuild/darwin-x64": "0.28.2",
+        "@esbuild/freebsd-arm64": "0.28.2",
+        "@esbuild/freebsd-x64": "0.28.2",
+        "@esbuild/linux-arm": "0.28.2",
+        "@esbuild/linux-arm64": "0.28.2",
+        "@esbuild/linux-ia32": "0.28.2",
+        "@esbuild/linux-loong64": "0.28.2",
+        "@esbuild/linux-mips64el": "0.28.2",
+        "@esbuild/linux-ppc64": "0.28.2",
+        "@esbuild/linux-riscv64": "0.28.2",
+        "@esbuild/linux-s390x": "0.28.2",
+        "@esbuild/linux-x64": "0.28.2",
+        "@esbuild/netbsd-arm64": "0.28.2",
+        "@esbuild/netbsd-x64": "0.28.2",
+        "@esbuild/openbsd-arm64": "0.28.2",
+        "@esbuild/openbsd-x64": "0.28.2",
+        "@esbuild/openharmony-arm64": "0.28.2",
+        "@esbuild/sunos-x64": "0.28.2",
+        "@esbuild/win32-arm64": "0.28.2",
+        "@esbuild/win32-ia32": "0.28.2",
+        "@esbuild/win32-x64": "0.28.2"
+      }
+    },
+    "node_modules/flatbuffers": {
+      "version": "25.9.23",
+      "resolved": "https://registry.npmjs.org/flatbuffers/-/flatbuffers-25.9.23.tgz",
+      "integrity": "sha512-MI1qs7Lo4Syw0EOzUl0xjs2lsoeqFku44KpngfIduHBYvzm8h2+7K8YMQh1JtVVVrUvhLpNwqVi4DERegUJhPQ==",
+      "license": "Apache-2.0"
+    },
+    "node_modules/guid-typescript": {
+      "version": "1.0.9",
+      "resolved": "https://registry.npmjs.org/guid-typescript/-/guid-typescript-1.0.9.tgz",
+      "integrity": "sha512-Y8T4vYhEfwJOTbouREvG+3XDsjr8E3kIr7uf+JZ0BYloFsttiHU0WfvANVsR7TxNUJa/WpCnw/Ino/p+DeBhBQ==",
+      "license": "ISC"
+    },
+    "node_modules/long": {
+      "version": "5.3.2",
+      "resolved": "https://registry.npmjs.org/long/-/long-5.3.2.tgz",
+      "integrity": "sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==",
+      "license": "Apache-2.0"
+    },
+    "node_modules/onnxruntime-common": {
+      "version": "1.30.0",
+      "resolved": "https://registry.npmjs.org/onnxruntime-common/-/onnxruntime-common-1.30.0.tgz",
+      "integrity": "sha512-7fdVWjAID1dVhH/G8qK3APARunV4VkBFoCQAP7qp4Wkab0mrorvmc+sqiT+mKXOzDqdjN5j+/Z9nb4gzNPWcyA==",
+      "license": "MIT"
+    },
+    "node_modules/onnxruntime-web": {
+      "version": "1.30.0",
+      "resolved": "https://registry.npmjs.org/onnxruntime-web/-/onnxruntime-web-1.30.0.tgz",
+      "integrity": "sha512-q0y+JrrtukXSzsBWEMccVfqX25LRmosXHF+CaRJmg8pZClzcV7svNc4rKY3jL02Vb7QmRMDs1SigqR4CXAfKYQ==",
+      "license": "MIT",
+      "dependencies": {
+        "flatbuffers": "^25.1.24",
+        "guid-typescript": "^1.0.9",
+        "long": "^5.2.3",
+        "onnxruntime-common": "1.30.0",
+        "platform": "^1.3.6",
+        "protobufjs": "^7.2.4"
+      }
+    },
+    "node_modules/platform": {
+      "version": "1.3.6",
+      "resolved": "https://registry.npmjs.org/platform/-/platform-1.3.6.tgz",
+      "integrity": "sha512-fnWVljUchTro6RiCFvCXBbNhJc2NijN7oIQxbwsyL0buWJPG85v81ehlHI9fXrJsMNgTofEoWIQeClKpgxFLrg==",
+      "license": "MIT"
+    },
+    "node_modules/protobufjs": {
+      "version": "7.6.6",
+      "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.6.6.tgz",
+      "integrity": "sha512-dYDWdjSl5RNb7SgPxGQcRU+GtvP7s2fpkrY0r432PcOIaZ0/rBcxEZnQN67iJhFuQiVw754JDoPruPCNdGsbjg==",
+      "hasInstallScript": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "@protobufjs/aspromise": "^1.1.2",
+        "@protobufjs/base64": "^1.1.2",
+        "@protobufjs/codegen": "^2.0.5",
+        "@protobufjs/eventemitter": "^1.1.1",
+        "@protobufjs/fetch": "^1.1.1",
+        "@protobufjs/float": "^1.0.2",
+        "@protobufjs/path": "^1.1.2",
+        "@protobufjs/pool": "^1.1.0",
+        "@protobufjs/utf8": "^1.1.1",
+        "@types/node": ">=13.7.0",
+        "long": "^5.3.2"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "8.9.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-8.9.0.tgz",
+      "integrity": "sha512-KTDyRTYX8sWmKXAikPHHSyc63CRPETMctyjKFupcC6OBLXT3xsN0e9aF7m+mIXutFWpUXuedtowG7iLOzp0kQg==",
+      "license": "MIT"
+    }
+  }
+}

sdk/typescript/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@vons/decision-sdk",
+  "version": "0.1.0",
+  "description": "Contract and host-boundary SDK for Vons decision models",
+  "type": "module",
+  "dependencies": {
+    "@huggingface/tokenizers": "0.2.0",
+    "onnxruntime-web": "1.30.0"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./onnx": "./src/onnx.ts"
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --test test/index.test.mjs test/onnx.test.mjs test/parity.test.mjs",
+    "build:browser": "esbuild demo/main.ts --bundle --format=esm --platform=browser --target=es2022 --outfile=demo/main.js",
+    "build:benchmark": "esbuild demo/benchmark.ts --bundle --format=esm --platform=browser --target=es2022 --outfile=demo/benchmark.js",
+    "build:parity": "esbuild demo/parity.ts --bundle --format=esm --platform=browser --target=es2022 --outfile=demo/parity.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "esbuild": "0.28.2"
+  },
+  "private": true,
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "SEE LICENSE IN LICENSE"
+}

sdk/typescript/src/index.ts

@@ -0,0 +1,255 @@
+export type QuestionType = "choice" | "boolean" | "score";
+export type Backend = "direct" | "diffusion";
+export type ResponseStatus = "ok" | "abstain";
+
+const validQuestionTypes = new Set<QuestionType>(["choice", "boolean", "score"]);
+
+export interface Question {
+  id: string;
+  type: QuestionType;
+  prompt: string;
+  options: string[];
+  rubric?: string[];
+}
+
+export interface DecisionRequest {
+  state: string | Record<string, unknown>;
+  questions: Question[];
+  backend?: Backend;
+  seed?: number;
+}
+
+export interface OptionProbability {
+  option: string;
+  probability: number;
+}
+
+export interface QuestionAnswer {
+  question_id: string;
+  choice: string | null;
+  probabilities: OptionProbability[];
+  confidence: number;
+  status: ResponseStatus;
+  abstain_reason?: string | null;
+}
+
+export interface DecisionResponse {
+  answers: QuestionAnswer[];
+  backend: Backend;
+  model_id: string;
+  metadata?: Record<string, unknown>;
+}
+
+export type ToolRisk = "low" | "medium" | "high" | "critical";
+
+export interface ToolCall {
+  name: string;
+  arguments: Record<string, unknown>;
+}
+
+export interface KASIProposal {
+  calls?: ToolCall[];
+  confidence: number;
+  risk?: string | null;
+  response?: string | null;
+}
+
+export type KASIAction = "call" | "clarify" | "confirm" | "refuse" | "respond";
+
+export interface KASIActionDecision {
+  action: KASIAction;
+  calls: ToolCall[];
+  prompt: string | null;
+  reason: string;
+}
+
+export interface DecisionBackend {
+  readonly backend: Backend;
+  decide(request: DecisionRequest): Promise<DecisionResponse>;
+}
+
+const toolNamePattern = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
+const validRisks = new Set<ToolRisk>(["low", "medium", "high", "critical"]);
+const riskRank: Record<ToolRisk, number> = { low: 0, medium: 1, high: 2, critical: 3 };
+
+function assertFiniteUnit(value: number, name: string): void {
+  if (!Number.isFinite(value) || value < 0 || value > 1) {
+    throw new TypeError(`${name} must be finite and in [0, 1]`);
+  }
+}
+
+function assertToolName(name: string): void {
+  if (typeof name !== "string" || !toolNamePattern.test(name)) {
+    throw new TypeError("tool name must match [A-Za-z0-9][A-Za-z0-9_.:-]{0,127}");
+  }
+}
+
+function normalizeRisk(value: string | null | undefined): ToolRisk | null {
+  return value && validRisks.has(value.trim().toLowerCase() as ToolRisk)
+    ? (value.trim().toLowerCase() as ToolRisk)
+    : null;
+}
+
+function stableJson(value: unknown): string {
+  if (value === null || typeof value !== "object") {
+    const primitive = JSON.stringify(value);
+    if (primitive === undefined) throw new TypeError("arguments must be JSON-compatible");
+    return primitive;
+  }
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b));
+  return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(",")}}`;
+}
+
+export function callFingerprint(call: ToolCall): string {
+  assertToolName(call.name);
+  // SHA-256 is supplied by the host in production. The portable SDK key is a
+  // canonical consent key; callers may hash it before persistence.
+  return stableJson({ name: call.name, arguments: call.arguments });
+}
+
+export function validateRequest(request: DecisionRequest, maxQuestions = 8, maxTokens = 512): void {
+  if (!request || typeof request !== "object") throw new TypeError("request must be an object");
+  if (!Number.isInteger(maxQuestions) || maxQuestions < 1) throw new TypeError("maxQuestions must be a positive integer");
+  if (!Number.isInteger(maxTokens) || maxTokens < 1) throw new TypeError("maxTokens must be a positive integer");
+  if (typeof request.state !== "string" && (!request.state || typeof request.state !== "object" || Array.isArray(request.state))) {
+    throw new TypeError("state must be a string or object");
+  }
+  if (typeof request.state === "string" && request.state.trim().length === 0) {
+    throw new TypeError("state must not be empty");
+  }
+  if (!Array.isArray(request.questions) || request.questions.length < 1 || request.questions.length > maxQuestions) {
+    throw new TypeError(`questions must contain 1..${maxQuestions} items`);
+  }
+  const ids = new Set<string>();
+  for (const question of request.questions) {
+    if (!question || typeof question !== "object") throw new TypeError("questions must contain objects");
+    if (typeof question.id !== "string" || !question.id || ids.has(question.id)) throw new TypeError("question ids must be unique and non-empty");
+    ids.add(question.id);
+    if (!validQuestionTypes.has(question.type)) throw new TypeError(`question ${question.id} has an invalid type`);
+    if (typeof question.prompt !== "string" || !question.prompt.trim()) throw new TypeError(`question ${question.id} has an empty prompt`);
+    if (!Array.isArray(question.options) || question.options.some((option) => typeof option !== "string" || !option.trim())) {
+      throw new TypeError(`question ${question.id} options must be strings`);
+    }
+    if (question.type === "boolean") {
+      if (question.options.length > 0 && JSON.stringify(question.options) !== JSON.stringify(["true", "false"])) {
+        throw new TypeError("boolean questions must use true/false options");
+      }
+    } else if (!Array.isArray(question.options) || question.options.length < 2 || question.options.length > 32) {
+      throw new TypeError(`question ${question.id} must contain 2..32 options`);
+    }
+    if (new Set(question.options).size !== question.options.length) throw new TypeError("question options must be unique");
+    if (question.rubric !== undefined && !Array.isArray(question.rubric)) {
+      throw new TypeError("question rubric must be a list");
+    }
+    if (question.type === "score" && (!question.rubric || question.rubric.length < 2 || question.rubric.length > 10)) {
+      throw new TypeError("score questions must contain a 2..10 item rubric");
+    }
+    if (question.type === "score" && question.rubric?.some((item) => typeof item !== "string")) {
+      throw new TypeError("score question rubric items must be strings");
+    }
+    if (question.type !== "score" && question.rubric?.length) {
+      throw new TypeError(`only score question ${question.id} may provide rubric`);
+    }
+  }
+  // Tokenizer-specific budget checks belong to the runtime adapter. A character
+  // estimate here would reject valid WordPiece inputs and cannot account for
+  // the aggregate state/question/all-candidate contract. Keep maxTokens in the
+  // signature for API compatibility and let adapters enforce their exact limit.
+  void maxTokens;
+}
+
+export function validateResponse(response: DecisionResponse): void {
+  if (!response || typeof response !== "object") throw new TypeError("response must be an object");
+  if (typeof response.model_id !== "string" || !response.model_id.trim()) throw new TypeError("model_id is required");
+  if (response.backend !== "direct" && response.backend !== "diffusion") throw new TypeError("invalid backend");
+  if (!Array.isArray(response.answers)) throw new TypeError("answers must be a list");
+  if (response.metadata !== undefined && (!response.metadata || typeof response.metadata !== "object" || Array.isArray(response.metadata))) {
+    throw new TypeError("metadata must be an object");
+  }
+  const ids = new Set<string>();
+  for (const answer of response.answers) {
+    if (!answer || typeof answer !== "object") throw new TypeError("answers must contain objects");
+    if (typeof answer.question_id !== "string" || !answer.question_id || ids.has(answer.question_id)) throw new TypeError("answer question ids must be unique and non-empty");
+    ids.add(answer.question_id);
+    if (!Array.isArray(answer.probabilities)) throw new TypeError("probabilities must be a list");
+    assertFiniteUnit(answer.confidence, "confidence");
+    const options = new Set<string>();
+    let total = 0;
+    for (const item of answer.probabilities) {
+      if (!item || typeof item !== "object" || typeof item.option !== "string" || !item.option) {
+        throw new TypeError("probability options must be non-empty strings");
+      }
+      if (options.has(item.option)) throw new TypeError("probability options must be unique");
+      options.add(item.option);
+      assertFiniteUnit(item.probability, "probability");
+      total += item.probability;
+    }
+    if (answer.probabilities.length > 0 && Math.abs(total - 1) > 1e-6) throw new TypeError("probabilities must sum to 1");
+    if (answer.status !== "ok" && answer.status !== "abstain") throw new TypeError("invalid response status");
+    if (answer.choice !== null && typeof answer.choice !== "string") throw new TypeError("choice must be a string or null");
+    if (answer.abstain_reason !== undefined && answer.abstain_reason !== null && typeof answer.abstain_reason !== "string") {
+      throw new TypeError("abstain_reason must be a string or null");
+    }
+    if (answer.status === "ok" && !answer.choice) throw new TypeError("ok answers require choice");
+    if (answer.status === "abstain" && (answer.choice !== null || !answer.abstain_reason?.trim())) {
+      throw new TypeError("abstain answers require a reason and no choice");
+    }
+    if (answer.status === "ok" && answer.probabilities.length > 0 && !options.has(answer.choice!)) {
+      throw new TypeError("choice must be present in probabilities");
+    }
+  }
+}
+
+export class KASIAdapter {
+  private readonly policy: ReadonlyMap<string, ToolRisk>;
+  private readonly threshold: number;
+
+  constructor(policy: Record<string, ToolRisk>, threshold = 0.55) {
+    if (!Number.isFinite(threshold) || threshold <= 0 || threshold > 1) throw new TypeError("invalid threshold");
+    this.threshold = threshold;
+    const entries: [string, ToolRisk][] = [];
+    for (const [name, risk] of Object.entries(policy)) {
+      assertToolName(name);
+      if (!validRisks.has(risk)) throw new TypeError(`invalid risk for ${name}`);
+      entries.push([name, risk]);
+    }
+    this.policy = new Map(entries);
+  }
+
+  decide(proposal: KASIProposal, confirmedCalls: ReadonlySet<string> = new Set()): KASIActionDecision {
+    assertFiniteUnit(proposal.confidence, "confidence");
+    const calls = proposal.calls ?? [];
+    if (calls.length > 0 && proposal.response) throw new TypeError("proposal cannot contain both calls and response");
+    if (proposal.response && !(proposal.calls?.length)) {
+      if (proposal.confidence >= this.threshold) return { action: "respond", calls: [], prompt: proposal.response, reason: "direct_response" };
+    }
+    if (proposal.confidence < this.threshold) return { action: "clarify", calls, prompt: "Please provide the missing information before acting.", reason: "low_confidence" };
+    if (calls.length === 0) return { action: "refuse", calls, prompt: "No safe candidate action is available.", reason: "no_proposed_call" };
+    const advisory = normalizeRisk(proposal.risk);
+    if (proposal.risk !== null && proposal.risk !== undefined && !advisory) {
+      return { action: "confirm", calls, prompt: "Confirm action with unknown model risk.", reason: "unknown_model_risk" };
+    }
+    for (const call of calls) {
+      assertToolName(call.name);
+      const hostRisk = this.policy.get(call.name);
+      if (!hostRisk) return { action: "refuse", calls: [], prompt: "Tool is not registered by the host.", reason: "unregistered_tool" };
+      const needsConsent = !advisory || Math.max(riskRank[hostRisk], riskRank[advisory]) >= riskRank.high;
+      if (needsConsent && !confirmedCalls.has(callFingerprint(call))) {
+        return { action: "confirm", calls, prompt: `Confirm action: ${call.name}(${stableJson(call.arguments)}).`, reason: "unconfirmed_or_unknown_risk" };
+      }
+    }
+    return { action: "call", calls, prompt: null, reason: "approved_by_host_policy" };
+  }
+}
+
+export function selectRuntime(preferred: "wasm" | "webgpu" = "wasm"): "wasm" | "webgpu" {
+  if (preferred === "webgpu") {
+    const scope = globalThis as { navigator?: { gpu?: unknown }; gpu?: unknown };
+    const gpu = scope.navigator?.gpu ?? scope.gpu;
+    if (!gpu) throw new Error("WebGPU is unavailable; choose wasm explicitly");
+    return "webgpu";
+  }
+  if (typeof WebAssembly === "undefined") throw new Error("WebAssembly is unavailable");
+  return "wasm";
+}

sdk/typescript/src/onnx.ts

@@ -0,0 +1,606 @@
+import { Tokenizer } from "@huggingface/tokenizers";
+
+import {
+  type Backend,
+  type DecisionBackend,
+  type DecisionRequest,
+  type DecisionResponse,
+  type Question,
+  type QuestionAnswer,
+  validateRequest,
+  validateResponse,
+} from "./index.ts";
+
+export type OnnxExecutionProvider = "wasm" | "webgpu";
+
+export interface BundleFileRecord {
+  path: string;
+  role: string;
+  bytes: number;
+  sha256: string;
+  runtime_loaded: boolean;
+  model_asset: boolean;
+}
+
+export interface BundleManifest {
+  schema_version: "vons.bundle.manifest/v1";
+  manifest: { path: string; sha256: string | null; self_hash_excluded: boolean };
+  metadata: {
+    backend: Backend;
+    model_id?: string;
+    option_count?: number;
+    sequence_length?: number;
+    input_names?: string[];
+    output_names?: string[];
+    graph?: {
+      external_data_locations?: string[];
+      inputs?: Array<{ name: string; dtype: string; shape: Array<number | string | null> | null }>;
+      outputs?: Array<{ name: string; dtype: string; shape: Array<number | string | null> | null }>;
+    };
+    [key: string]: unknown;
+  };
+  files: BundleFileRecord[];
+  summary: {
+    model_asset_bytes: number;
+    complete_download_bytes: number;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+
+export interface TokenizedCandidate {
+  inputIds: number[];
+  attentionMask: number[];
+  tokenTypeIds: number[];
+}
+
+export interface OnnxWebBackendOptions {
+  /** Use a URL when the manifest is served beside the browser bundle. */
+  manifestUrl?: string | URL;
+  /** Supply a previously fetched manifest when the caller controls loading. */
+  manifest?: BundleManifest;
+  /** Pin the exact manifest bytes expected by a release or measurement run. */
+  expectedManifestSha256?: string;
+  /** Required with an in-memory manifest unless the browser has a useful base URI. */
+  baseUrl?: string | URL;
+  provider?: OnnxExecutionProvider;
+  wasmPaths?: string | Record<string, string>;
+  wasmNumThreads?: number;
+  abstainThreshold?: number;
+  answerabilityThreshold?: number;
+  /** Override Direct's live candidate count for padding-cost experiments. */
+  directOptionSlots?: number;
+  /** Freeze the exact noise array when a cross-runtime comparison needs it. */
+  initialNoise?: (length: number, seed: number | undefined, questionIndex: number) => Float32Array;
+  /** Optional instrumentation hook; it is not part of the decision response contract. */
+  onTiming?: (sample: OnnxTimingSample) => void;
+  /** Optional local parity trace; disabled by default and not part of the response contract. */
+  onTrace?: (sample: OnnxTraceSample) => void;
+  fetch?: typeof fetch;
+  signal?: AbortSignal;
+}
+
+export interface OnnxRuntimeInfo {
+  provider: OnnxExecutionProvider;
+  ortVersion: string | null;
+  wasmNumThreads: number | null;
+  webgpuAdapterRequested: boolean;
+  webgpuDeviceRequested: boolean;
+}
+
+export interface OnnxTimingSample {
+  questionId: string;
+  live_candidates: number;
+  allocated_candidates: number;
+  live_tokens: number;
+  sequence_length: number;
+  tokenizeMs: number;
+  prepareFeedMs: number;
+  inferenceAndReadbackMs: number;
+  postprocessMs: number;
+  totalRequestMs: number;
+}
+
+export interface OnnxTraceSample {
+  questionId: string;
+  inputIds: number[];
+  attentionMask: number[];
+  tokenTypeIds: number[];
+  optionMask: number[];
+  initialNoise: number[] | null;
+  rawScores: number[];
+  answerabilityLogit: number;
+  probabilities: number[];
+  answer: QuestionAnswer;
+}
+
+interface OrtTensor {
+  data: ArrayLike<number>;
+  dims: readonly number[];
+}
+
+interface OrtSession {
+  run(feeds: Record<string, unknown>): Promise<Record<string, OrtTensor>>;
+  release(): Promise<void>;
+  inputNames: readonly string[];
+  outputNames: readonly string[];
+}
+
+interface OrtModule {
+  Tensor: new (type: string, data: ArrayLike<number> | ArrayLike<bigint>, dims: readonly number[]) => unknown;
+  InferenceSession: { create(model: ArrayBufferLike, options?: Record<string, unknown>): Promise<OrtSession> };
+  env: {
+    wasm: { wasmPaths?: string | Record<string, string>; numThreads?: number };
+    versions?: { common?: string; web?: string };
+  };
+}
+
+interface GpuLike {
+  requestAdapter(): Promise<{ requestDevice(): Promise<unknown> } | null>;
+}
+
+interface LoadedAssets {
+  manifest: BundleManifest;
+  manifestHash: string;
+  model: Uint8Array;
+  tokenizer: Tokenizer;
+  externalData: Array<{ path: string; data: Uint8Array }>;
+}
+
+const EXPECTED_SCHEMA = "vons.bundle.manifest/v1";
+const REQUIRED_DIRECT_INPUTS = ["input_ids", "attention_mask", "token_type_ids", "option_mask"];
+const REQUIRED_DIFFUSION_INPUTS = [...REQUIRED_DIRECT_INPUTS, "initial_noise"];
+
+function assertFiniteUnit(value: number, name: string): void {
+  if (!Number.isFinite(value) || value < 0 || value > 1) throw new TypeError(`${name} must be finite and in [0, 1]`);
+}
+
+function stableJson(value: unknown): string {
+  if (value === null || typeof value !== "object") {
+    const primitive = JSON.stringify(value);
+    if (primitive === undefined) throw new TypeError("state must be JSON-compatible");
+    return primitive;
+  }
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b));
+  return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(",")}}`;
+}
+
+export function serializeState(state: DecisionRequest["state"]): string {
+  return typeof state === "string" ? state : stableJson(state);
+}
+
+export function candidateText(state: DecisionRequest["state"], question: Question, option: string): string {
+  return `${serializeState(state)}\nQuestion: ${question.prompt}\nCandidate: ${option}`;
+}
+
+export function candidateListText(state: DecisionRequest["state"], question: Question, options: readonly string[]): string {
+  return `${serializeState(state)}\nQuestion: ${question.prompt}\nCandidates:\n${options.join("\n")}`;
+}
+
+function assertManifest(manifest: BundleManifest): void {
+  if (!manifest || manifest.schema_version !== EXPECTED_SCHEMA) {
+    throw new TypeError(`unsupported bundle manifest schema: ${manifest?.schema_version ?? "missing"}`);
+  }
+  if (!manifest.metadata || (manifest.metadata.backend !== "direct" && manifest.metadata.backend !== "diffusion")) {
+    throw new TypeError("bundle manifest metadata.backend must be direct or diffusion");
+  }
+  if (!Array.isArray(manifest.files) || manifest.files.length === 0) throw new TypeError("bundle manifest has no files");
+  const paths = new Set<string>();
+  for (const item of manifest.files) {
+    if (!item || typeof item.path !== "string" || item.path.length === 0 || paths.has(item.path)) {
+      throw new TypeError(`bundle manifest contains an invalid or duplicate path: ${item?.path ?? "missing"}`);
+    }
+    if (item.path.startsWith("/") || item.path.includes("..") || /^[A-Za-z]:[\\/]/.test(item.path)) {
+      throw new TypeError(`bundle manifest path must be bundle-relative: ${item.path}`);
+    }
+    if (!Number.isSafeInteger(item.bytes) || item.bytes < 0 || !/^[0-9a-f]{64}$/.test(item.sha256)) {
+      throw new TypeError(`bundle manifest has invalid bytes or sha256: ${item.path}`);
+    }
+    paths.add(item.path);
+  }
+}
+
+function getBaseUrl(options: OnnxWebBackendOptions): URL {
+  if (options.baseUrl) return new URL(options.baseUrl.toString(), globalThis.location?.href ?? "http://localhost/");
+  if (options.manifestUrl) return new URL(options.manifestUrl.toString(), globalThis.location?.href ?? "http://localhost/");
+  if (typeof globalThis.location?.href === "string") return new URL(globalThis.location.href);
+  throw new TypeError("baseUrl or manifestUrl is required when running outside a browser");
+}
+
+function resolveAssetUrl(base: URL, path: string): URL {
+  if (
+    path.startsWith("/") ||
+    path.includes("\\") ||
+    path.includes("..") ||
+    /%(?:2e|2f|5c)/i.test(path) ||
+    /[?#]/.test(path) ||
+    /^[A-Za-z]:[\\/]/.test(path) ||
+    /^[A-Za-z][A-Za-z+.-]*:/.test(path)
+  ) {
+    throw new TypeError(`bundle asset path must be relative: ${path}`);
+  }
+  const resolved = new URL(path, base);
+  const basePath = base.pathname.endsWith("/") ? base.pathname : `${base.pathname}/`;
+  if (resolved.origin !== base.origin || !resolved.pathname.startsWith(basePath)) {
+    throw new TypeError(`bundle asset path escapes its manifest directory: ${path}`);
+  }
+  return resolved;
+}
+
+async function sha256(bytes: Uint8Array): Promise<string> {
+  if (!globalThis.crypto?.subtle) throw new Error("Web Crypto SHA-256 is unavailable");
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes as unknown as BufferSource);
+  return Array.from(new Uint8Array(digest), (value) => value.toString(16).padStart(2, "0")).join("");
+}
+
+async function fetchBytes(fetchImpl: typeof fetch, url: URL, signal?: AbortSignal): Promise<Uint8Array> {
+  const response = await fetchImpl(url, { signal });
+  if (!response.ok) throw new Error(`failed to fetch ${url}: HTTP ${response.status}`);
+  return new Uint8Array(await response.arrayBuffer());
+}
+
+async function loadManifest(options: OnnxWebBackendOptions, fetchImpl: typeof fetch): Promise<{ manifest: BundleManifest; manifestHash: string; base: URL }> {
+  if (options.expectedManifestSha256 !== undefined && !/^[0-9a-f]{64}$/.test(options.expectedManifestSha256)) {
+    throw new TypeError("expectedManifestSha256 must be a lowercase SHA-256 digest");
+  }
+  if (options.manifest) {
+    assertManifest(options.manifest);
+    const manifestBytes = new TextEncoder().encode(stableJson(options.manifest));
+    const manifestHash = await sha256(manifestBytes);
+    if (options.expectedManifestSha256 !== undefined && manifestHash !== options.expectedManifestSha256) {
+      throw new Error(`bundle manifest SHA-256 mismatch: ${manifestHash}`);
+    }
+    return { manifest: options.manifest, base: getBaseUrl(options), manifestHash };
+  }
+  if (!options.manifestUrl) throw new TypeError("manifest or manifestUrl is required");
+  const url = new URL(options.manifestUrl.toString(), globalThis.location?.href ?? "http://localhost/");
+  const bytes = await fetchBytes(fetchImpl, url, options.signal);
+  let manifest: BundleManifest;
+  try {
+    manifest = JSON.parse(new TextDecoder().decode(bytes)) as BundleManifest;
+  } catch (error) {
+    throw new TypeError(`bundle manifest is not valid JSON: ${String(error)}`);
+  }
+  assertManifest(manifest);
+  const manifestHash = await sha256(bytes);
+  if (options.expectedManifestSha256 !== undefined && manifestHash !== options.expectedManifestSha256) {
+    throw new Error(`bundle manifest SHA-256 mismatch: ${manifestHash}`);
+  }
+  return { manifest, base: new URL(".", url), manifestHash };
+}
+
+async function loadAssets(options: OnnxWebBackendOptions): Promise<LoadedAssets> {
+  const fetchImpl = options.fetch ?? globalThis.fetch?.bind(globalThis);
+  if (!fetchImpl) throw new Error("fetch is unavailable; provide options.fetch");
+  const { manifest, manifestHash, base } = await loadManifest(options, fetchImpl);
+  const cache = new Map<string, Uint8Array>();
+  const getFile = async (record: BundleFileRecord): Promise<Uint8Array> => {
+    const cached = cache.get(record.path);
+    if (cached) return cached;
+    const bytes = await fetchBytes(fetchImpl, resolveAssetUrl(base, record.path), options.signal);
+    if (bytes.byteLength !== record.bytes) throw new Error(`bundle byte count mismatch: ${record.path}`);
+    const actual = await sha256(bytes);
+    if (actual !== record.sha256) throw new Error(`bundle SHA-256 mismatch: ${record.path}`);
+    cache.set(record.path, bytes);
+    return bytes;
+  };
+  const graph = manifest.files.find((item) => item.role === "model_graph");
+  if (!graph) throw new Error("bundle manifest has no model graph");
+  const tokenizerJson = manifest.files.find((item) => item.role === "tokenizer" && item.path.endsWith("tokenizer.json"));
+  const tokenizerConfig = manifest.files.find((item) => item.role === "tokenizer" && item.path.endsWith("tokenizer_config.json"));
+  if (!tokenizerJson || !tokenizerConfig) throw new Error("bundle manifest must include tokenizer.json and tokenizer_config.json");
+  const model = await getFile(graph);
+  const tokenizer = new Tokenizer(
+    JSON.parse(new TextDecoder().decode(await getFile(tokenizerJson))) as object,
+    JSON.parse(new TextDecoder().decode(await getFile(tokenizerConfig))) as object,
+  );
+  const locations = manifest.metadata.graph?.external_data_locations ?? [];
+  const externalData: Array<{ path: string; data: Uint8Array }> = [];
+  for (const location of locations) {
+    const record = manifest.files.find((item) => item.role === "model_external_data" && item.path === location);
+    if (!record) throw new Error(`external-data location is missing from the manifest: ${location}`);
+    externalData.push({ path: location, data: await getFile(record) });
+  }
+  return { manifest, manifestHash, model, tokenizer, externalData };
+}
+
+function encodeCandidate(tokenizer: Tokenizer, text: string, sequenceLength: number): TokenizedCandidate {
+  const encoded = tokenizer.encode(text, { return_token_type_ids: true });
+  const inputIds = [...encoded.ids];
+  const attentionMask = [...encoded.attention_mask];
+  const tokenTypeIds = [...encoded.token_type_ids];
+  if (inputIds.length !== attentionMask.length || inputIds.length !== tokenTypeIds.length) {
+    throw new Error("tokenizer returned arrays with different lengths");
+  }
+  if (inputIds.length > sequenceLength) {
+    throw new RangeError(`tokenized candidate has ${inputIds.length} tokens; the bundle limit is ${sequenceLength}`);
+  }
+  if (inputIds.some((value) => !Number.isSafeInteger(value) || value < 0)) throw new Error("tokenizer returned an invalid token id");
+  return { inputIds, attentionMask, tokenTypeIds };
+}
+
+export function tokenizeCandidates(
+  tokenizer: Tokenizer,
+  state: DecisionRequest["state"],
+  question: Question,
+  options: readonly string[],
+  sequenceLength: number,
+): TokenizedCandidate[] {
+  return options.map((option) => encodeCandidate(tokenizer, candidateText(state, question, option), sequenceLength));
+}
+
+function padCandidates(candidates: readonly TokenizedCandidate[], slots: number, sequenceLength: number, paddingId: number): {
+  inputIds: BigInt64Array;
+  attentionMask: BigInt64Array;
+  tokenTypeIds: BigInt64Array;
+  optionMask: Uint8Array;
+} {
+  if (!Number.isInteger(slots) || slots < candidates.length || slots < 1) throw new RangeError("invalid candidate slot count");
+  const inputIds = new BigInt64Array(slots * sequenceLength);
+  const attentionMask = new BigInt64Array(slots * sequenceLength);
+  const tokenTypeIds = new BigInt64Array(slots * sequenceLength);
+  const optionMask = new Uint8Array(slots);
+  inputIds.fill(BigInt(paddingId));
+  for (let optionIndex = 0; optionIndex < candidates.length; optionIndex += 1) {
+    const candidate = candidates[optionIndex];
+    optionMask[optionIndex] = 1;
+    const offset = optionIndex * sequenceLength;
+    for (let tokenIndex = 0; tokenIndex < candidate.inputIds.length; tokenIndex += 1) {
+      inputIds[offset + tokenIndex] = BigInt(candidate.inputIds[tokenIndex]);
+      attentionMask[offset + tokenIndex] = BigInt(candidate.attentionMask[tokenIndex]);
+      tokenTypeIds[offset + tokenIndex] = BigInt(candidate.tokenTypeIds[tokenIndex]);
+    }
+  }
+  return { inputIds, attentionMask, tokenTypeIds, optionMask };
+}
+
+export function seededNoise(length: number, seed: number | undefined, questionIndex: number): Float32Array {
+  if (!Number.isInteger(length) || length < 1) throw new RangeError("noise length must be positive");
+  let state = ((seed ?? 0) ^ (questionIndex + 1) * 0x9e3779b9) >>> 0;
+  const result = new Float32Array(length);
+  const nextUnit = (): number => {
+    state = (Math.imul(state ^ (state >>> 16), 0x45d9f3b) + 0x27100001) >>> 0;
+    // Open interval (0, 1) avoids log(0) while keeping the stream deterministic.
+    return (state + 1) / 4294967297;
+  };
+  for (let index = 0; index < length; index += 1) {
+    const radius = Math.sqrt(-2 * Math.log(nextUnit()));
+    const angle = 2 * Math.PI * nextUnit();
+    result[index] = radius * Math.cos(angle);
+    if (index + 1 < length) {
+      result[index + 1] = radius * Math.sin(angle);
+      index += 1;
+    }
+  }
+  return result;
+}
+
+function sigmoid(value: number): number {
+  if (!Number.isFinite(value)) throw new Error("model returned a non-finite answerability logit");
+  return value >= 0 ? 1 / (1 + Math.exp(-value)) : Math.exp(value) / (1 + Math.exp(value));
+}
+
+function softmax(values: readonly number[]): number[] {
+  if (values.length === 0 || values.some((value) => Number.isNaN(value))) throw new Error("model returned invalid option scores");
+  const maximum = Math.max(...values);
+  if (!Number.isFinite(maximum)) throw new Error("model returned no finite option score");
+  const exponentials = values.map((value) => Math.exp(value - maximum));
+  const total = exponentials.reduce((sum, value) => sum + value, 0);
+  if (!Number.isFinite(total) || total <= 0) throw new Error("could not normalize model option scores");
+  return exponentials.map((value) => value / total);
+}
+
+function tensor(runtime: OrtModule, type: string, data: ArrayLike<number> | ArrayLike<bigint>, dims: readonly number[]): unknown {
+  return new runtime.Tensor(type, data, dims);
+}
+
+function tensorValues(output: OrtTensor | undefined, expectedLength: number, name: string): number[] {
+  if (!output || !output.dims) throw new Error(`missing output tensor: ${name}`);
+  const values = Array.from(output.data, Number);
+  if (values.length !== expectedLength) throw new Error(`output ${name} has ${values.length} values; expected ${expectedLength}`);
+  return values;
+}
+
+async function loadOrt(provider: OnnxExecutionProvider, options: OnnxWebBackendOptions): Promise<{ runtime: OrtModule; info: OnnxRuntimeInfo }> {
+  if (provider === "webgpu") {
+    const gpu = (globalThis.navigator as Navigator & { gpu?: GpuLike } | undefined)?.gpu;
+    if (!gpu) throw new Error("WebGPU is unavailable; choose wasm explicitly");
+    const adapter = await gpu.requestAdapter();
+    if (!adapter) throw new Error("WebGPU adapter request returned null");
+    await adapter.requestDevice();
+  }
+  const runtime = (provider === "webgpu"
+    ? await import("onnxruntime-web/webgpu")
+    : await import("onnxruntime-web/wasm")) as unknown as OrtModule;
+  if (options.wasmPaths) runtime.env.wasm.wasmPaths = options.wasmPaths;
+  if (provider === "wasm") {
+    if (options.wasmNumThreads !== undefined) {
+      if (!Number.isInteger(options.wasmNumThreads) || options.wasmNumThreads < 1) throw new TypeError("wasmNumThreads must be a positive integer");
+      runtime.env.wasm.numThreads = options.wasmNumThreads;
+    }
+  }
+  return {
+    runtime,
+    info: {
+      provider,
+      ortVersion: runtime.env.versions?.web ?? runtime.env.versions?.common ?? null,
+      wasmNumThreads: provider === "wasm" ? runtime.env.wasm.numThreads ?? null : null,
+      webgpuAdapterRequested: provider === "webgpu",
+      webgpuDeviceRequested: provider === "webgpu",
+    },
+  };
+}
+
+export class OnnxWebBackend implements DecisionBackend {
+  readonly backend: Backend;
+  readonly runtimeInfo: OnnxRuntimeInfo;
+  readonly manifest: BundleManifest;
+  readonly manifestHash: string;
+  private readonly tokenizer: Tokenizer;
+  private readonly runtime: OrtModule;
+  private readonly session: OrtSession;
+  private readonly sequenceLength: number;
+  private readonly optionCount: number;
+  private readonly paddingId: number;
+  private readonly abstainThreshold: number;
+  private readonly answerabilityThreshold: number;
+  private readonly directOptionSlots: number | undefined;
+  private readonly initialNoise: OnnxWebBackendOptions["initialNoise"];
+  private readonly onTiming: OnnxWebBackendOptions["onTiming"];
+  private readonly onTrace: OnnxWebBackendOptions["onTrace"];
+  private disposed = false;
+  private constructor(assets: LoadedAssets, runtime: OrtModule, runtimeInfo: OnnxRuntimeInfo, session: OrtSession, options: OnnxWebBackendOptions) {
+    this.backend = assets.manifest.metadata.backend;
+    this.runtimeInfo = runtimeInfo;
+    this.manifest = assets.manifest;
+    this.manifestHash = assets.manifestHash;
+    this.tokenizer = assets.tokenizer;
+    this.runtime = runtime;
+    this.session = session;
+    this.sequenceLength = assets.manifest.metadata.sequence_length ?? 512;
+    this.optionCount = assets.manifest.metadata.option_count ?? 32;
+    this.paddingId = assets.tokenizer.token_to_id("[PAD]") ?? 0;
+    this.abstainThreshold = options.abstainThreshold ?? 0.55;
+    this.answerabilityThreshold = options.answerabilityThreshold ?? 0.5;
+    this.directOptionSlots = options.directOptionSlots;
+    this.initialNoise = options.initialNoise;
+    this.onTiming = options.onTiming;
+    this.onTrace = options.onTrace;
+  }
+
+  static async create(options: OnnxWebBackendOptions = {}): Promise<OnnxWebBackend> {
+    const assets = await loadAssets(options);
+    const provider = options.provider ?? "wasm";
+    assertFiniteUnit(options.abstainThreshold ?? 0.55, "abstainThreshold");
+    assertFiniteUnit(options.answerabilityThreshold ?? 0.5, "answerabilityThreshold");
+    const { runtime, info } = await loadOrt(provider, options);
+    const expectedInputs = assets.manifest.metadata.backend === "diffusion" ? REQUIRED_DIFFUSION_INPUTS : REQUIRED_DIRECT_INPUTS;
+    const modelInputs = assets.manifest.metadata.input_names ?? expectedInputs;
+    if (JSON.stringify(modelInputs) !== JSON.stringify(expectedInputs)) throw new Error("bundle input contract is not supported by this backend");
+    const outputNames = assets.manifest.metadata.output_names ?? (assets.manifest.metadata.backend === "diffusion" ? ["scores", "answerability"] : ["logits", "answerability"]);
+    const session = await runtime.InferenceSession.create(assets.model.buffer, {
+      executionProviders: [provider],
+      externalData: assets.externalData,
+    });
+    try {
+      if (session.inputNames.length !== expectedInputs.length || expectedInputs.some((name) => !session.inputNames.includes(name))) {
+        throw new Error(`loaded session inputs do not match the manifest: ${session.inputNames.join(",")}`);
+      }
+      if (outputNames.some((name) => !session.outputNames.includes(name))) throw new Error("loaded session outputs do not match the manifest");
+    } catch (error) {
+      await session.release();
+      throw error;
+    }
+    return new OnnxWebBackend(assets, runtime, info, session, options);
+  }
+
+  async decide(request: DecisionRequest): Promise<DecisionResponse> {
+    if (this.disposed) throw new Error("ONNX Runtime session has been disposed");
+    validateRequest(request);
+    const answers: QuestionAnswer[] = [];
+    for (const [questionIndex, question] of request.questions.entries()) {
+      const requestStarted = performance.now();
+      if (question.type === "score") {
+        throw new Error("score questions are not supported by this candidate-selection ONNX head");
+      }
+      const options = question.type === "boolean" && question.options.length === 0 ? ["true", "false"] : question.options;
+      const slots = this.backend === "diffusion" ? this.optionCount : this.directOptionSlots ?? options.length;
+      if (options.length === 0 || options.length > this.optionCount || slots > this.optionCount) {
+        throw new RangeError(`question ${question.id} has unsupported candidate count`);
+      }
+      const aggregateTokenCount = this.tokenizer.encode(candidateListText(request.state, question, options)).ids.length;
+      if (aggregateTokenCount > this.sequenceLength) {
+        throw new RangeError(`question ${question.id} exceeds the ${this.sequenceLength}-token aggregate input budget (tokens=${aggregateTokenCount})`);
+      }
+      const tokenizeStarted = performance.now();
+      const encoded = tokenizeCandidates(this.tokenizer, request.state, question, options, this.sequenceLength);
+      const tokenized = performance.now();
+      const padded = padCandidates(encoded, slots, this.sequenceLength, this.paddingId);
+      let traceNoise: Float32Array | null = null;
+      const feeds: Record<string, unknown> = {
+        input_ids: tensor(this.runtime, "int64", padded.inputIds, [1, slots, this.sequenceLength]),
+        attention_mask: tensor(this.runtime, "int64", padded.attentionMask, [1, slots, this.sequenceLength]),
+        token_type_ids: tensor(this.runtime, "int64", padded.tokenTypeIds, [1, slots, this.sequenceLength]),
+        option_mask: tensor(this.runtime, "bool", padded.optionMask, [1, slots]),
+      };
+      if (this.backend === "diffusion") {
+        const noise = this.initialNoise?.(this.optionCount, request.seed, questionIndex) ?? seededNoise(this.optionCount, request.seed, questionIndex);
+        if (!(noise instanceof Float32Array) || noise.length !== this.optionCount) throw new TypeError("initialNoise must return a Float32Array with option_count values");
+        traceNoise = noise;
+        feeds.initial_noise = tensor(this.runtime, "float32", noise, [1, this.optionCount]);
+      }
+      const inferenceStarted = performance.now();
+      const outputs = await this.session.run(feeds);
+      const readbackCompleted = performance.now();
+      const scoreName = this.backend === "diffusion" ? "scores" : "logits";
+      const scores = tensorValues(outputs[scoreName], slots, scoreName).slice(0, options.length);
+      const probabilities = softmax(scores);
+      const answerabilityLogit = tensorValues(outputs.answerability, 1, "answerability")[0];
+      const answerability = sigmoid(answerabilityLogit);
+      const choiceIndex = probabilities.reduce((best, value, index) => value > probabilities[best] ? index : best, 0);
+      const confidence = probabilities[choiceIndex] * answerability;
+      const abstainReason = answerability < this.answerabilityThreshold
+        ? "answerability_below_threshold"
+        : confidence < this.abstainThreshold ? "confidence_below_threshold" : null;
+      const answer: QuestionAnswer = {
+        question_id: question.id,
+        choice: abstainReason ? null : options[choiceIndex],
+        probabilities: options.map((option, index) => ({ option, probability: probabilities[index] })),
+        confidence,
+        status: abstainReason ? "abstain" : "ok",
+        abstain_reason: abstainReason,
+      };
+      answers.push(answer);
+      this.onTrace?.({
+        questionId: question.id,
+        inputIds: Array.from(padded.inputIds, Number),
+        attentionMask: Array.from(padded.attentionMask, Number),
+        tokenTypeIds: Array.from(padded.tokenTypeIds, Number),
+        optionMask: Array.from(padded.optionMask, Number),
+        initialNoise: traceNoise === null ? null : Array.from(traceNoise),
+        rawScores: scores,
+        answerabilityLogit,
+        probabilities,
+        answer,
+      });
+      const postprocessCompleted = performance.now();
+      this.onTiming?.({
+        questionId: question.id,
+        live_candidates: encoded.length,
+        allocated_candidates: slots,
+        live_tokens: encoded.reduce((total, candidate) => total + candidate.inputIds.length, 0),
+        sequence_length: this.sequenceLength,
+        tokenizeMs: tokenized - tokenizeStarted,
+        prepareFeedMs: inferenceStarted - tokenized,
+        inferenceAndReadbackMs: readbackCompleted - inferenceStarted,
+        postprocessMs: postprocessCompleted - readbackCompleted,
+        totalRequestMs: postprocessCompleted - requestStarted,
+      });
+    }
+    const response: DecisionResponse = {
+      answers,
+      backend: this.backend,
+      model_id: this.manifest.metadata.model_id ?? `vons-${this.backend}-onnx-web`,
+      metadata: {
+        provider: this.runtimeInfo.provider,
+        ort_version: this.runtimeInfo.ortVersion,
+        sequence_length: this.sequenceLength,
+        candidate_slots: this.backend === "diffusion" ? this.optionCount : this.directOptionSlots ?? "live",
+        tokenizer: "@huggingface/tokenizers@0.2.0",
+      },
+    };
+    validateResponse(response);
+    return response;
+  }
+
+  async dispose(): Promise<void> {
+    if (this.disposed) return;
+    this.disposed = true;
+    await this.session.release();
+  }
+}
+
+export async function createOnnxWebBackend(options: OnnxWebBackendOptions = {}): Promise<OnnxWebBackend> {
+  return OnnxWebBackend.create(options);
+}

sdk/typescript/test/index.test.mjs

@@ -0,0 +1,65 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+const sdk = await import("../src/index.ts");
+
+test("host policy refuses unregistered tools and requires exact high-risk consent", () => {
+  const adapter = new sdk.KASIAdapter({ unlock: "high" });
+  const first = { name: "unlock", arguments: { target: "lab" } };
+  const second = { name: "unlock", arguments: { target: "vault" } };
+  assert.equal(adapter.decide({ calls: [second], confidence: 0.9, risk: "low" }).action, "confirm");
+  assert.equal(adapter.decide({ calls: [second], confidence: 0.9, risk: "low" }, new Set([sdk.callFingerprint(first)])).action, "confirm");
+  assert.equal(adapter.decide({ calls: [second], confidence: 0.9, risk: "low" }, new Set([sdk.callFingerprint(second)])).action, "call");
+  assert.equal(new sdk.KASIAdapter({}).decide({ calls: [{ name: "read", arguments: {} }], confidence: 0.9, risk: "low" }).action, "refuse");
+});
+
+test("request and response validators enforce the shared contract", () => {
+  assert.doesNotThrow(() => sdk.validateRequest({
+    state: "ready",
+    questions: [{ id: "q", type: "choice", prompt: "Pick", options: ["a", "b"] }],
+  }));
+  assert.throws(() => sdk.validateResponse({
+    answers: [{ question_id: "q", choice: "a", probabilities: [{ option: "a", probability: 0.5 }], confidence: 0.9, status: "ok" }],
+    backend: "direct",
+    model_id: "test",
+  }));
+  assert.throws(() => sdk.validateRequest({
+    state: "ready",
+    questions: [{ id: "q", type: "choice", prompt: "Pick", options: ["a", "b"], rubric: ["bad"] }],
+  }), /only score question/);
+  assert.doesNotThrow(() => sdk.validateRequest({
+    state: "x".repeat(2000),
+    questions: [{ id: "q", type: "choice", prompt: "Pick", options: ["a", "b"] }],
+  }));
+  assert.doesNotThrow(() => sdk.validateRequest({
+    state: "x".repeat(200),
+    questions: Array.from({ length: 8 }, (_, index) => ({
+      id: `q-${index}`,
+      type: "choice",
+      prompt: "Pick",
+      options: ["a", "b"],
+    })),
+  }));
+  assert.doesNotThrow(() => sdk.validateRequest({
+    state: "ready",
+    questions: [{ id: "q", type: "choice", prompt: "Pick", options: ["x".repeat(2000), "b"] }],
+  }));
+  assert.throws(() => sdk.validateRequest({
+    state: "ready",
+    questions: [{ id: "q", type: "choice", prompt: "Pick", options: ["", "b"] }],
+  }), /options must be strings/);
+  assert.doesNotThrow(() => sdk.validateRequest({
+    state: "ready",
+    questions: [{ id: "q", type: "choice", prompt: "Pick", options: ["a", "b"] }],
+  }, 8, 512));
+});
+
+test("runtime selection is explicit", () => {
+  assert.equal(sdk.selectRuntime("wasm"), "wasm");
+  assert.throws(() => sdk.selectRuntime("webgpu"), /WebGPU is unavailable/);
+  const previousGpu = globalThis.gpu;
+  globalThis.gpu = {};
+  assert.equal(sdk.selectRuntime("webgpu"), "webgpu");
+  if (previousGpu === undefined) delete globalThis.gpu;
+  else globalThis.gpu = previousGpu;
+});

sdk/typescript/test/onnx.test.mjs

@@ -0,0 +1,101 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+const onnx = await import("../src/onnx.ts");
+
+// Deliberately synthetic: public contract tests must not require pilot weights.
+function testManifest() {
+  const record = (path, role, bytes = 4) => ({
+    path, role, bytes, sha256: "1".repeat(64), runtime_loaded: true, model_asset: true,
+  });
+  return {
+    schema_version: "vons.bundle.manifest/v1",
+    manifest: { path: "bundle-manifest.json", sha256: null, self_hash_excluded: true },
+    metadata: { backend: "direct", option_count: 2, sequence_length: 32 },
+    files: [
+      record("model.onnx", "model_graph"),
+      record("tokenizer.json", "tokenizer"),
+      record("tokenizer_config.json", "tokenizer"),
+    ],
+    summary: { model_asset_bytes: 12, complete_download_bytes: 12 },
+  };
+}
+
+test("structured state and the training text template are deterministic", () => {
+  const question = { id: "q", type: "choice", prompt: "Pick", options: ["A"] };
+  assert.equal(onnx.serializeState({ z: 1, a: ["x", 2] }), '{"a":["x",2],"z":1}');
+  assert.equal(onnx.candidateText({ z: 1, a: ["x", 2] }, question, "A"), '{"a":["x",2],"z":1}\nQuestion: Pick\nCandidate: A');
+});
+
+test("default diffusion noise is deterministic Gaussian, not a bounded uniform surrogate", () => {
+  const first = onnx.seededNoise(32, 7, 0);
+  const second = onnx.seededNoise(32, 7, 0);
+  assert.deepEqual(Array.from(first), Array.from(second));
+  assert.ok(first.some((value) => value > 1 || value < -1));
+  assert.ok(Array.from(first).every(Number.isFinite));
+});
+
+test("tokenizer ids, masks, and overflow behavior are explicit", async () => {
+  const { Tokenizer } = await import("@huggingface/tokenizers");
+  const tokenizer = new Tokenizer(
+    {
+      version: "1.0",
+      added_tokens: [],
+      normalizer: { type: "BertNormalizer", clean_text: true, handle_chinese_chars: true, strip_accents: null, lowercase: true },
+      pre_tokenizer: { type: "BertPreTokenizer" },
+      post_processor: { type: "BertProcessing", sep: ["[SEP]", 2], cls: ["[CLS]", 1] },
+      decoder: { type: "WordPiece", prefix: "##", cleanup: true },
+      model: { type: "WordPiece", unk_token: "[UNK]", continuing_subword_prefix: "##", max_input_chars_per_word: 100,
+        vocab: { "[UNK]": 0, "[CLS]": 1, "[SEP]": 2, ready: 3, question: 4, pick: 5, candidate: 6, ":": 7, a: 8, b: 9, "/": 10, "?": 11, "中": 12, "文": 13 } },
+    },
+    { tokenizer_class: "BertTokenizer", unk_token: "[UNK]", cls_token: "[CLS]", sep_token: "[SEP]", model_max_length: 512 },
+  );
+  const question = { id: "q", type: "choice", prompt: "Pick", options: ["A/B?", "中文"] };
+  const values = onnx.tokenizeCandidates(tokenizer, "ready", question, question.options, 512);
+  assert.deepEqual(values[0].inputIds, [1, 3, 4, 7, 5, 6, 7, 8, 10, 9, 11, 2]);
+  assert.deepEqual(values[1].inputIds, [1, 3, 4, 7, 5, 6, 7, 12, 13, 2]);
+  assert.equal(values[0].inputIds.length, values[0].attentionMask.length);
+  assert.deepEqual(new Set(values[0].attentionMask), new Set([1]));
+  assert.throws(() => onnx.tokenizeCandidates(tokenizer, "x", question, ["x".repeat(10000)], 4), /bundle limit/);
+});
+
+test("manifest integrity is checked before a runtime session is created", async () => {
+  const manifest = testManifest();
+  const original = manifest.files.find((item) => item.role === "model_graph");
+  original.sha256 = "0".repeat(64);
+  const fetch = async () => new Response(new Uint8Array(original.bytes), { status: 200 });
+  await assert.rejects(
+    onnx.createOnnxWebBackend({ manifest, baseUrl: "https://example.test/bundle/", fetch }),
+    /SHA-256 mismatch/,
+  );
+});
+
+test("release runs can pin manifest bytes and encoded traversal is rejected", async () => {
+  const manifest = testManifest();
+  await assert.rejects(
+    onnx.createOnnxWebBackend({
+      manifest,
+      baseUrl: "https://example.test/bundle/",
+      expectedManifestSha256: "0".repeat(64),
+      fetch: async () => new Response(new Uint8Array(), { status: 200 }),
+    }),
+    /manifest SHA-256 mismatch/,
+  );
+  const escaped = structuredClone(manifest);
+  escaped.files.find((item) => item.role === "model_graph").path = "%2e%2e/escape.onnx";
+  await assert.rejects(
+    onnx.createOnnxWebBackend({
+      manifest: escaped,
+      baseUrl: "https://example.test/bundle/",
+      fetch: async () => new Response(new Uint8Array(), { status: 200 }),
+    }),
+    /bundle asset path must be relative/,
+  );
+});
+
+test("malformed manifests are rejected before provider selection", async () => {
+  await assert.rejects(
+    onnx.createOnnxWebBackend({ manifest: { schema_version: "vons.bundle.manifest/v1" }, provider: "webgpu" }),
+    /metadata.backend|baseUrl|manifestUrl/,
+  );
+});

sdk/typescript/test/parity.test.mjs

@@ -0,0 +1,18 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+const { buildParityFixtures } = await import("../demo/parity.ts");
+const { validateRequest } = await import("../src/index.ts");
+
+test("parity matrix covers candidate counts, question types, and explicit overflow", () => {
+  const fixtures = buildParityFixtures();
+  assert.ok(fixtures.length >= 20);
+  assert.deepEqual(new Set(fixtures.map((item) => item.matrix.candidate_count)), new Set([2, 4, 8, 16, 32]));
+  assert.ok(fixtures.some((item) => item.request.questions[0]?.type === "boolean"));
+  assert.ok(fixtures.some((item) => item.request.questions[0]?.type === "score"));
+  assert.ok(fixtures.some((item) => item.expectedFailure));
+  assert.equal(new Set(fixtures.map((item) => item.id)).size, fixtures.length);
+  for (const fixture of fixtures.filter((item) => !item.expectedFailure)) {
+    assert.doesNotThrow(() => validateRequest(fixture.request), fixture.id);
+  }
+});

tests/test_browser_benchmark.py

@@ -0,0 +1,161 @@
+import importlib.util
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+
+def _load_tool():
+    path = Path(__file__).parents[1] / "tools" / "verify_browser_benchmark.py"
+    spec = importlib.util.spec_from_file_location("vons_browser_benchmark", path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError("could not load browser benchmark verifier")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+benchmark_tool = _load_tool()
+
+
+def _sample(repeat: int, status: str = "ok") -> dict[str, object]:
+    values = {
+        "tokenizeMs": 1.0 + repeat,
+        "prepareFeedMs": 2.0 + repeat,
+        "inferenceAndReadbackMs": 3.0 + repeat,
+        "postprocessMs": 4.0 + repeat,
+        "totalRequestMs": 10.0 + repeat,
+    }
+    if status == "error":
+        values = {key: None for key in values}
+    return {
+        **values,
+        "session_start": 1,
+        "repeat": repeat,
+        "run_id": "run-1",
+        "case_id": f"case-{repeat + 1}",
+        "backend": "direct",
+        "requested_provider": "wasm",
+        "observed_provider": None,
+        "observed_provider_status": "session_created; execution_partition_not_exposed",
+        "live_candidates": 4 if status == "ok" else None,
+        "allocated_candidates": 4 if status == "ok" else None,
+        "live_tokens": 12 if status == "ok" else None,
+        "sequence_length": 512 if status == "ok" else None,
+        "bundle_hash": "a" * 64,
+        "tokenizer_hash": "b" * 64,
+        "input_hash": "c" * 64,
+        "noise_hash": None,
+        "status": status,
+        "js_heap_used_bytes_before": None,
+        "js_heap_used_bytes_after": None,
+    }
+
+
+class BrowserBenchmarkTests(unittest.TestCase):
+    def test_recomputes_raw_samples_and_allows_unavailable_memory(self) -> None:
+        report = {
+            "schema": "vons.browser-benchmark/v1",
+            "sessions": 1,
+            "warmup_excluded_per_session": 1,
+            "repeats_per_session": 3,
+            "run_id": "run-1",
+            "backend": "direct",
+            "cases": 1,
+            "requested_provider": "wasm",
+            "environment": {"user_agent": "test", "cross_origin_isolated": False},
+            "runtime_info": None,
+            "execution_provider_evidence": "test evidence",
+            "session_records": [{"session_start": 1, "load_ms": 5.0, "status": "ok"}],
+            "samples": [_sample(0), _sample(1), _sample(2, "error")],
+        }
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "report.json"
+            path.write_text(json.dumps(report), encoding="utf-8")
+            result = benchmark_tool.verify_report(path)
+
+        self.assertEqual(result["sample_rows"], 3)
+        self.assertEqual(result["successful_samples"], 2)
+        self.assertEqual(result["failed_samples"], 1)
+        self.assertEqual(result["recomputed_summary"]["total_request_ms_p50"], 10.5)
+        self.assertIsNone(result["recomputed_summary"]["js_heap_before_max"])
+
+    def test_rejects_failed_sample_with_fabricated_timing(self) -> None:
+        report = {
+            "schema": "vons.browser-benchmark/v1",
+            "sessions": 1,
+            "warmup_excluded_per_session": 1,
+            "repeats_per_session": 1,
+            "run_id": "run-1",
+            "backend": "direct",
+            "cases": 1,
+            "requested_provider": "webgpu",
+            "environment": {"user_agent": "test", "cross_origin_isolated": False},
+            "runtime_info": None,
+            "execution_provider_evidence": "test evidence",
+            "session_records": [{"session_start": 1, "load_ms": 5.0, "status": "ok"}],
+            "samples": [_sample(0, "error")],
+        }
+        report["samples"][0]["requested_provider"] = "webgpu"
+        report["samples"][0]["totalRequestMs"] = 2.0
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "report.json"
+            path.write_text(json.dumps(report), encoding="utf-8")
+            with self.assertRaises(ValueError):
+                benchmark_tool.verify_report(path)
+
+    def test_rejects_sample_without_provenance_hashes(self) -> None:
+        report = {
+            "schema": "vons.browser-benchmark/v1",
+            "sessions": 1,
+            "warmup_excluded_per_session": 1,
+            "repeats_per_session": 1,
+            "run_id": "run-1",
+            "backend": "direct",
+            "cases": 1,
+            "requested_provider": "wasm",
+            "environment": {"user_agent": "test", "cross_origin_isolated": False},
+            "runtime_info": None,
+            "execution_provider_evidence": "test evidence",
+            "session_records": [{"session_start": 1, "load_ms": 5.0, "status": "ok"}],
+            "samples": [_sample(0)],
+        }
+        report["samples"][0]["input_hash"] = None
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "report.json"
+            path.write_text(json.dumps(report), encoding="utf-8")
+            with self.assertRaises(ValueError):
+                benchmark_tool.verify_report(path)
+
+    def test_rejects_partial_session_matrix_by_default(self) -> None:
+        report = {
+            "schema": "vons.browser-benchmark/v1",
+            "sessions": 2,
+            "warmup_excluded_per_session": 1,
+            "repeats_per_session": 1,
+            "run_id": "run-1",
+            "backend": "direct",
+            "cases": 1,
+            "requested_provider": "wasm",
+            "environment": {"user_agent": "test", "cross_origin_isolated": False},
+            "runtime_info": None,
+            "execution_provider_evidence": "test evidence",
+            "session_records": [
+                {"session_start": 1, "load_ms": 5.0, "status": "ok"},
+                {"session_start": 2, "load_ms": 1.0, "status": "error", "error_kind": "fetch"},
+            ],
+            "samples": [_sample(0)],
+        }
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "report.json"
+            path.write_text(json.dumps(report), encoding="utf-8")
+            with self.assertRaises(ValueError):
+                benchmark_tool.verify_report(path)
+            result = benchmark_tool.verify_report(path, allow_incomplete=True)
+
+        self.assertFalse(result["complete"])
+        self.assertTrue(result["incomplete_reasons"])
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_browser_benchmark_summary.py

@@ -0,0 +1,1130 @@
+"""Tests for tools/summarize_browser_benchmark.py.
+
+Covers:
+- Exact expected linearly interpolated percentiles (p50, p95) for known datasets
+- Null/failed/timeout row preservation with nullable timing slots
+- Malformed rows, non-finite timings, wrong types, bad SHA256
+- Homogeneous condition enforcement and mixed-condition rejection
+- Duplicate (run_id, session_start, repeat) identity rejection
+- Insufficient-observation completeness flag without error
+- CLI behavior via subprocess on a small valid fixture
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+TOOLS_DIR = Path(__file__).resolve().parent.parent / "tools"
+SUMMARY_TOOL = TOOLS_DIR / "summarize_browser_benchmark.py"
+
+sys.path.insert(0, str(TOOLS_DIR))
+from summarize_browser_benchmark import (  # noqa: E402, RUF100
+    TIMING_FIELDS,
+    _validate_row,
+    percentile,
+    validate_and_aggregate,
+    validate_and_aggregate_report,
+)
+
+SHA_A = "a" * 64
+SHA_B = "b" * 64
+SHA_C = "c" * 64
+SHA_D = "d" * 64
+SHA_NOISE = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+
+BASE_ENV = {
+    "user_agent": "TestBrowser/1.0",
+    "cross_origin_isolated": True,
+    "platform": "Test OS",
+}
+
+
+def _provenance(*, warmup: int = 10, semantics: str = "page_reload") -> dict[str, Any]:
+    return {
+        "environment": dict(BASE_ENV),
+        "execution_provider_evidence": "window.ort.env.backend='wasm'",
+        "warmup_excluded_per_session": warmup,
+        "session_start_semantics": semantics,
+    }
+
+
+def _row(
+    *,
+    session_start: int = 1,
+    repeat: int = 0,
+    case_id: str = "case-0",
+    backend: str = "direct",
+    status: str = "ok",
+    error: str | None = None,
+    timings: dict[str, float] | None = None,
+    candidate_count: int = 4,
+    padded_option_slots: int = 8,
+    sequence_length: int = 64,
+    seed: int = 42,
+    noise_hash: str | None = None,
+    heap_before: float | None = None,
+    heap_after: float | None = None,
+    observed_provider: str = "wasm",
+) -> dict[str, Any]:
+    if backend == "diffusion" and noise_hash is None:
+        noise_hash = SHA_NOISE
+    ok_timings: dict[str, float] = (
+        timings
+        if timings is not None
+        else {
+            "tokenizeMs": 1.0,
+            "prepareFeedMs": 0.5,
+            "inferenceAndReadbackMs": 10.0,
+            "postprocessMs": 0.25,
+            "totalRequestMs": 11.75,
+        }
+    )
+    row: dict[str, Any] = {
+        "run_id": "run-alpha",
+        "session_start": session_start,
+        "repeat": repeat,
+        "case_id": case_id,
+        "backend": backend,
+        "requested_provider": "wasm",
+        "observed_provider": observed_provider,
+        "bundle_hash": SHA_A,
+        "tokenizer_hash": SHA_B,
+        "input_hash": SHA_C,
+        "noise_hash": noise_hash,
+        "candidate_count": candidate_count,
+        "padded_option_slots": padded_option_slots,
+        "sequence_length": sequence_length,
+        "seed": seed,
+        "ort_version": "1.20.1",
+        "status": status,
+        "error": error,
+        "provenance": _provenance(),
+    }
+    if status == "ok":
+        row.update(ok_timings)
+        if heap_before is not None:
+            row["js_heap_used_bytes_before"] = heap_before
+        if heap_after is not None:
+            row["js_heap_used_bytes_after"] = heap_after
+    else:
+        for field in TIMING_FIELDS:
+            row[field] = None
+        if timings is not None:
+            for field, value in timings.items():
+                row[field] = value
+        if error is None:
+            row["error"] = "simulated failure"
+    return row
+
+
+def _write_jsonl(tmp_path: Path, rows: list[dict[str, Any]], *, name: str = "input.jsonl") -> Path:
+    path = tmp_path / name
+    with path.open("w", encoding="utf-8") as handle:
+        for row in rows:
+            handle.write(json.dumps(row, sort_keys=True) + "\n")
+    return path
+
+
+# ---------------------------------------------------------------------------
+# percentile linear interpolation correctness
+# ---------------------------------------------------------------------------
+
+
+class TestPercentile:
+    def test_empty_is_null(self) -> None:
+        assert percentile([], 0.5) is None
+
+    def test_single_value(self) -> None:
+        assert percentile([7.0], 0.5) == 7.0
+
+    def test_two_values_p50_is_midpoint(self) -> None:
+        # index = (2-1)*0.5 = 0.5 -> lower=0, upper=1 -> midpoint
+        assert percentile([10.0, 20.0], 0.5) == pytest.approx(15.0)
+
+    def test_two_values_p95_near_upper(self) -> None:
+        # index = 1 * 0.95 = 0.95 -> 10 + 10*0.95 = 19.5
+        assert percentile([10.0, 20.0], 0.95) == pytest.approx(19.5)
+
+    def test_four_values_p50_exact_interpolation(self) -> None:
+        # sorted: [1,2,3,4]; index = (4-1)*0.5 = 1.5
+        # lower=1 -> 2, upper=2 -> 3, fraction=0.5 -> 2 + 1*0.5 = 2.5
+        assert percentile([3.0, 1.0, 4.0, 2.0], 0.5) == pytest.approx(2.5)
+
+    def test_eight_values_p95(self) -> None:
+        values = [float(x) for x in range(1, 9)]
+        # sorted: [1..8]; index = (8-1)*0.95 = 7*0.95 = 6.65
+        # lower=6 -> 7.0, upper=7 -> 8.0, delta=0.65 -> 7.0 + 1.0*0.65 = 7.65
+        assert percentile(values, 0.95) == pytest.approx(7.65)
+
+    def test_fraction_out_of_range_rejected(self) -> None:
+        with pytest.raises(ValueError):
+            percentile([1.0, 2.0], 1.5)
+        with pytest.raises(ValueError):
+            percentile([1.0, 2.0], -0.1)
+
+
+# ---------------------------------------------------------------------------
+# Row validation
+# ---------------------------------------------------------------------------
+
+
+class TestRowValidation:
+    def test_missing_status_rejected(self) -> None:
+        row = _row()
+        del row["status"]
+        with pytest.raises(ValueError, match="missing required field status"):
+            _validate_row(row, 1)
+
+    def test_invalid_status_string_rejected(self) -> None:
+        row = _row(status="pending")
+        with pytest.raises(ValueError, match="status must be ok, error, or timeout"):
+            _validate_row(row, 1)
+
+    def test_ok_row_with_error_value_rejected(self) -> None:
+        row = _row(status="ok", error="should be empty")
+        with pytest.raises(ValueError, match="error must be null for successful"):
+            _validate_row(row, 1)
+
+    def test_failed_row_with_partial_timings_allowed(self) -> None:
+        row = _row(status="error", timings={"totalRequestMs": 500.0, "tokenizeMs": 10.0})
+        assert row["status"] == "error"
+        assert row["totalRequestMs"] == 500.0
+        assert row["tokenizeMs"] == 10.0
+        assert row["prepareFeedMs"] is None
+        _validate_row(row, 1)
+
+    def test_successful_row_missing_timing_rejected(self) -> None:
+        row = _row()
+        del row["inferenceAndReadbackMs"]
+        with pytest.raises(ValueError, match="successful sample requires inferenceAndReadbackMs"):
+            _validate_row(row, 1)
+
+    def test_nonfinite_timing_rejected(self) -> None:
+        row = _row(timings={"tokenizeMs": math.nan, "prepareFeedMs": 0.5,
+                            "inferenceAndReadbackMs": 10.0, "postprocessMs": 0.25,
+                            "totalRequestMs": 11.75})
+        with pytest.raises((ValueError, TypeError), match="finite"):
+            _validate_row(row, 1)
+
+    def test_negative_timing_rejected(self) -> None:
+        row = _row(timings={"tokenizeMs": -1.0, "prepareFeedMs": 0.5,
+                            "inferenceAndReadbackMs": 10.0, "postprocessMs": 0.25,
+                            "totalRequestMs": 11.75})
+        with pytest.raises(ValueError, match="finite non-negative"):
+            _validate_row(row, 1)
+
+    def test_invalid_sha256_rejected(self) -> None:
+        row = _row()
+        row["bundle_hash"] = "short-and-wrong"
+        with pytest.raises(ValueError, match="SHA-256 hex string"):
+            _validate_row(row, 1)
+
+    def test_uppercase_sha256_rejected(self) -> None:
+        row = _row()
+        row["bundle_hash"] = "A" * 64
+        with pytest.raises(ValueError, match="lowercase SHA-256"):
+            _validate_row(row, 1)
+
+    def test_non_positive_shape_rejected(self) -> None:
+        row = _row(candidate_count=0)
+        with pytest.raises(ValueError, match="positive integer"):
+            _validate_row(row, 1)
+        row2 = _row(padded_option_slots=-5)
+        with pytest.raises(ValueError, match="positive integer"):
+            _validate_row(row2, 2)
+        row3 = _row(sequence_length=0)
+        with pytest.raises(ValueError, match="positive integer"):
+            _validate_row(row3, 3)
+
+    def test_diffusion_noise_required(self) -> None:
+        row = _row(backend="diffusion", noise_hash=None)
+        row["noise_hash"] = None
+        with pytest.raises(ValueError, match="noise_hash is required for diffusion"):
+            _validate_row(row, 1)
+
+    def test_repeat_negative_rejected(self) -> None:
+        row = _row(repeat=-1)
+        with pytest.raises(ValueError, match="repeat must be a non-negative integer"):
+            _validate_row(row, 1)
+
+    def test_requested_provider_must_be_wasm_or_webgpu(self) -> None:
+        row = _row()
+        row["requested_provider"] = "cpu"
+        with pytest.raises(ValueError, match="requested_provider must be wasm or webgpu"):
+            _validate_row(row, 1)
+
+
+# ---------------------------------------------------------------------------
+# End-to-end aggregation with actual expected percentiles
+# ---------------------------------------------------------------------------
+
+
+def _build_120row_fixture(
+    *,
+    backend: str = "direct",
+    extra_failures: int = 0,
+    warmup: int = 10,
+) -> list[dict[str, Any]]:
+    """10 sessions x 12 repeats = 120 rows with deterministic increasing timings.
+
+    totalRequestMs values for successful rows = 1.0, 2.0, ..., N_success.0.
+    p50 (120 successes, all ok):
+      index = (120-1)*0.5 = 59.5 -> values[59]=60.0, values[60]=61.0, frac=0.5 -> 60.5
+    p95:
+      index = 119*0.95 = 113.05 -> values[113]=114.0, values[114]=115.0, frac=0.05
+      -> 114.0 + 1.0*0.05 = 114.05
+    """
+    rows: list[dict[str, Any]] = []
+    counter = 0
+    for session in range(1, 11):
+        for repeat in range(12):
+            counter += 1
+            if extra_failures > 0 and counter % 15 == 0:
+                rows.append(
+                    _row(
+                        session_start=session,
+                        repeat=repeat,
+                        case_id=f"case-{counter}",
+                        backend=backend,
+                        status="error",
+                        error="simulated",
+                    )
+                )
+                extra_failures -= 1
+            else:
+                total = float(counter)
+                tokenize = 0.1 * counter
+                prepare = 0.05 * counter
+                inference = 0.8 * counter
+                post = 0.05 * counter
+                rows.append(
+                    _row(
+                        session_start=session,
+                        repeat=repeat,
+                        case_id=f"case-{counter}",
+                        backend=backend,
+                        status="ok",
+                        timings={
+                            "tokenizeMs": tokenize,
+                            "prepareFeedMs": prepare,
+                            "inferenceAndReadbackMs": inference,
+                            "postprocessMs": post,
+                            "totalRequestMs": total,
+                        },
+                        heap_before=1000.0 + counter,
+                        heap_after=2000.0 + counter,
+                    )
+                )
+            rows[-1]["provenance"] = _provenance(warmup=warmup)
+    return rows
+
+
+class TestAggregationPercentiles:
+    def test_120rows_percentiles_match_exact_expected(self, tmp_path: Path) -> None:
+        rows = _build_120row_fixture()
+        input_path = _write_jsonl(tmp_path, rows)
+        summary = validate_and_aggregate(input_path)
+
+        assert summary["sample_counts"]["successful"] == 120
+        assert summary["sample_counts"]["failed"] == 0
+        assert summary["sample_counts"]["unique_session_starts"] == 10
+        assert summary["measurement_completeness"]["complete"] is True
+
+        p50 = summary["stage_percentiles_ms"]["totalRequestMs"]["p50"]
+        p95 = summary["stage_percentiles_ms"]["totalRequestMs"]["p95"]
+        assert p50 == pytest.approx(60.5)
+        assert p95 == pytest.approx(114.05)
+
+        # tokenizeMs values = 0.1 * counter for counter=1..120
+        # sorted values are 0.1, 0.2, ..., 12.0
+        # p50: index=59.5 -> 6.0 + (6.1-6.0)*0.5 = 6.05
+        assert summary["stage_percentiles_ms"]["tokenizeMs"]["p50"] == pytest.approx(6.05)
+        # p95: index=113.05 -> values[113]=11.4, values[114]=11.5, frac=0.05 -> 11.405
+        assert summary["stage_percentiles_ms"]["tokenizeMs"]["p95"] == pytest.approx(11.405)
+
+    def test_failed_rows_counted_timings_nullable(self, tmp_path: Path) -> None:
+        rows = _build_120row_fixture(extra_failures=8)
+        input_path = _write_jsonl(tmp_path, rows)
+        summary = validate_and_aggregate(input_path)
+
+        assert summary["sample_counts"]["successful"] == 112
+        assert summary["sample_counts"]["failed"] == 8
+        assert summary["measurement_completeness"]["complete"] is True
+
+        # 112 successes: totalRequestMs are the 112 counter values that
+        # are not divisible by 15. Counters divisible by 15 (15,30,...,105,120)
+        # are failures. Total counters divisible by 15 up to 120: 120//15=8.
+        # totalRequestMs values are 1..14,16..29,...,106..119 (8 missing
+        # values: 15,30,45,60,75,90,105,120). All increasing order is still
+        # preserved because values increase monotonically with counter and
+        # only the multiples of 15 are removed.
+        #
+        # For percentile of 112 values:
+        # p50 index = (112-1)*0.5 = 55.5 -> values[55] and values[56]
+        # Before each multiple-of-15 threshold, 1 value has been skipped per
+        # prior group. Which values are at index 55/56?
+        # For each group of 15 counters, 14 survive. Group 1 (1-14) -> indices 0..13 (14).
+        # Group 2 (16-29) -> indices 14..27 (14, cumulative 28).
+        # Group 3 (31-44) -> indices 28..41 (14, cumulative 42).
+        # Group 4 (46-59) -> indices 42..55 (14, cumulative 56).
+        # So index 55 = last of group 4 -> counter 59 (value 59.0).
+        # Index 56 = first of group 5 -> counter 61 (value 61.0).
+        # Interpolation at 55.5 -> 0.5 fraction: 59.0 + 2.0 * 0.5 = 60.0
+        p50 = summary["stage_percentiles_ms"]["totalRequestMs"]["p50"]
+        assert p50 == pytest.approx(60.0)
+
+    def test_heap_maxima_from_observations_only(self, tmp_path: Path) -> None:
+        rows = _build_120row_fixture()
+        input_path = _write_jsonl(tmp_path, rows)
+        summary = validate_and_aggregate(input_path)
+        # counter 1..120 -> heap_before = 1000 + counter -> max at 1120
+        # counter 1..120 -> heap_after = 2000 + counter -> max at 2120
+        assert summary["heap_maxima_bytes"]["js_heap_used_bytes_before"] == pytest.approx(1120.0)
+        assert summary["heap_maxima_bytes"]["js_heap_used_bytes_after"] == pytest.approx(2120.0)
+
+    def test_all_null_heap_yields_null_maxima(self, tmp_path: Path) -> None:
+        rows = _build_120row_fixture()
+        for row in rows:
+            if row["status"] == "ok":
+                row.pop("js_heap_used_bytes_before", None)
+                row.pop("js_heap_used_bytes_after", None)
+        input_path = _write_jsonl(tmp_path, rows)
+        summary = validate_and_aggregate(input_path)
+        assert summary["heap_maxima_bytes"]["js_heap_used_bytes_before"] is None
+        assert summary["heap_maxima_bytes"]["js_heap_used_bytes_after"] is None
+
+
+# ---------------------------------------------------------------------------
+# Empty input, duplicates, mixed conditions
+# ---------------------------------------------------------------------------
+
+
+class TestValidationFailuresAggregate:
+    def test_empty_input_raises(self, tmp_path: Path) -> None:
+        path = tmp_path / "empty.jsonl"
+        path.write_text("", encoding="utf-8")
+        with pytest.raises(ValueError, match="no samples"):
+            validate_and_aggregate(path)
+
+    def test_duplicate_identity_raises(self, tmp_path: Path) -> None:
+        rows = [
+            _row(session_start=1, repeat=0, case_id="a"),
+            _row(session_start=1, repeat=0, case_id="b"),
+        ]
+        input_path = _write_jsonl(tmp_path, rows)
+        with pytest.raises(ValueError, match="duplicate.*identity"):
+            validate_and_aggregate(input_path)
+
+    def test_mixed_bundle_hash_raises(self, tmp_path: Path) -> None:
+        rows = [_row(session_start=1, repeat=0), _row(session_start=1, repeat=1)]
+        rows[1]["bundle_hash"] = SHA_D
+        input_path = _write_jsonl(tmp_path, rows)
+        with pytest.raises(ValueError, match="mixed experimental conditions"):
+            validate_and_aggregate(input_path)
+
+    def test_mixed_backend_raises(self, tmp_path: Path) -> None:
+        rows = [
+            _row(session_start=1, repeat=0, backend="direct"),
+            _row(session_start=1, repeat=1, backend="diffusion", noise_hash=SHA_NOISE),
+        ]
+        input_path = _write_jsonl(tmp_path, rows)
+        with pytest.raises(ValueError, match="mixed experimental conditions"):
+            validate_and_aggregate(input_path)
+
+    def test_mixed_environment_raises(self, tmp_path: Path) -> None:
+        rows = [_row(session_start=1, repeat=0), _row(session_start=1, repeat=1)]
+        rows[1]["provenance"] = _provenance()
+        rows[1]["provenance"]["environment"]["platform"] = "Different OS"
+        input_path = _write_jsonl(tmp_path, rows)
+        with pytest.raises(ValueError, match="mixed experimental conditions"):
+            validate_and_aggregate(input_path)
+
+    def test_mixed_warmup_raises(self, tmp_path: Path) -> None:
+        rows = [_row(session_start=1, repeat=0), _row(session_start=1, repeat=1)]
+        rows[1]["provenance"] = _provenance(warmup=20)
+        input_path = _write_jsonl(tmp_path, rows)
+        with pytest.raises(ValueError, match="mixed experimental conditions"):
+            validate_and_aggregate(input_path)
+
+    def test_diffusion_backend_homogeneous(self, tmp_path: Path) -> None:
+        """Diffusion samples must carry noise_hash; varying noise_hash by row is allowed."""
+        rows = []
+        for session in range(1, 7):
+            for repeat in range(20):
+                idx = session * 100 + repeat
+                rows.append(
+                    _row(
+                        session_start=session,
+                        repeat=repeat,
+                        case_id=f"case-{idx}",
+                        backend="diffusion",
+                        noise_hash=f"{idx:x}".zfill(64),
+                    )
+                )
+        input_path = _write_jsonl(tmp_path, rows)
+        summary = validate_and_aggregate(input_path)
+        assert summary["experimental_condition"]["backend"] == "diffusion"
+        assert summary["sample_counts"]["successful"] == 120
+        assert summary["sample_counts"]["failed"] == 0
+
+
+# ---------------------------------------------------------------------------
+# Completeness flag and provenance semantics
+# ---------------------------------------------------------------------------
+
+
+class TestCompletenessAndProvenance:
+    def test_insufficient_sessions_reported_incomplete(self, tmp_path: Path) -> None:
+        rows = []
+        for session in range(1, 4):  # only 3 sessions
+            for repeat in range(50):
+                rows.append(
+                    _row(
+                        session_start=session,
+                        repeat=repeat,
+                        case_id=f"case-{session}-{repeat}",
+                    )
+                )
+        # warmup per session = 10, rows = 150 -> two thresholds satisfied,
+        # but session count < 5
+        input_path = _write_jsonl(tmp_path, rows)
+        summary = validate_and_aggregate(input_path)
+        comp = summary["measurement_completeness"]
+        assert comp["complete"] is False
+        assert comp["actual_session_starts"] == 3
+        reasons = " ".join(comp["incomplete_reasons"])
+        assert "independent session starts" in reasons
+
+    def test_insufficient_warmup_reported_incomplete(self, tmp_path: Path) -> None:
+        rows = _build_120row_fixture(warmup=5)
+        input_path = _write_jsonl(tmp_path, rows)
+        summary = validate_and_aggregate(input_path)
+        comp = summary["measurement_completeness"]
+        assert comp["complete"] is False
+        assert comp["actual_warmup_excluded_per_session"] == 5
+
+    def test_120rows_10sessions_is_complete(self, tmp_path: Path) -> None:
+        rows = _build_120row_fixture()
+        input_path = _write_jsonl(tmp_path, rows)
+        summary = validate_and_aggregate(input_path)
+        assert summary["measurement_completeness"]["complete"] is True
+        assert summary["measurement_completeness"]["incomplete_reasons"] == []
+
+    def test_page_semantics_not_process_cold_claimable(self, tmp_path: Path) -> None:
+        rows = [_row(session_start=1, repeat=0)]
+        rows[0]["provenance"]["session_start_semantics"] = "in_page_repeat"
+        input_path = _write_jsonl(tmp_path, rows)
+        summary = validate_and_aggregate(input_path)
+        assert summary["process_cold_claimable"] is False
+
+    def test_process_restart_semantics_still_false_v1(self, tmp_path: Path) -> None:
+        rows = [_row(session_start=1, repeat=0)]
+        rows[0]["provenance"]["session_start_semantics"] = "process_restart"
+        input_path = _write_jsonl(tmp_path, rows)
+        summary = validate_and_aggregate(input_path)
+        assert summary["process_cold_claimable"] is False
+        assert "always False regardless of semantics string" in summary["process_cold_note"]
+
+    def test_requested_provider_match_still_false_v1(self, tmp_path: Path) -> None:
+        rows = [
+            _row(session_start=1, repeat=0, observed_provider="wasm"),
+            _row(session_start=1, repeat=1, observed_provider="wasm"),
+        ]
+        rows[0]["provenance"]["execution_provider_evidence"] = "window.ort.env.backend='wasm'"
+        input_path = _write_jsonl(tmp_path, rows)
+        summary = validate_and_aggregate(input_path)
+        assert summary["requested_is_proven"] is False
+        assert summary["experimental_condition"]["observed_provider"] == "wasm"
+        assert summary["experimental_condition"]["provenance"]["execution_provider_evidence"] == "window.ort.env.backend='wasm'"
+        assert "requested_is_proven is always False in v1" in summary["provider_claim_note"]
+
+    def test_observed_provider_mismatch_not_proven(self, tmp_path: Path) -> None:
+        rows = [_row(session_start=1, repeat=0, observed_provider=None)]
+        input_path = _write_jsonl(tmp_path, rows)
+        summary = validate_and_aggregate(input_path)
+        assert summary["requested_is_proven"] is False
+
+
+# ---------------------------------------------------------------------------
+# CLI integration
+# ---------------------------------------------------------------------------
+
+
+class TestCLI:
+    def test_cli_writes_summary(self, tmp_path: Path) -> None:
+        rows = _build_120row_fixture()
+        input_path = _write_jsonl(tmp_path, rows)
+        output_path = tmp_path / "summary.json"
+        result = subprocess.run(
+            [
+                sys.executable,
+                str(SUMMARY_TOOL),
+                "--input",
+                str(input_path),
+                "--output",
+                str(output_path),
+            ],
+            capture_output=True,
+            check=False,
+            text=True,
+        )
+        assert result.returncode == 0, result.stderr
+        assert output_path.exists()
+        loaded = json.loads(output_path.read_text(encoding="utf-8"))
+        assert loaded["schema"] == "vons.browser-benchmark-summary/v1"
+        assert loaded["sample_counts"]["successful"] == 120
+        assert loaded["stage_percentiles_ms"]["totalRequestMs"]["p50"] == pytest.approx(60.5)
+
+    def test_cli_validation_fails_before_writing(self, tmp_path: Path) -> None:
+        rows = [
+            _row(session_start=1, repeat=0),
+            _row(session_start=1, repeat=0, case_id="dup"),
+        ]
+        input_path = _write_jsonl(tmp_path, rows)
+        output_path = tmp_path / "summary.json"
+        result = subprocess.run(
+            [
+                sys.executable,
+                str(SUMMARY_TOOL),
+                "--input",
+                str(input_path),
+                "--output",
+                str(output_path),
+            ],
+            capture_output=True,
+            check=False,
+            text=True,
+        )
+        assert result.returncode != 0
+        assert not output_path.exists() or output_path.stat().st_size == 0
+
+
+# ---------------------------------------------------------------------------
+# Error rows preserve nullable timing slots at summary level (not erased)
+# ---------------------------------------------------------------------------
+
+
+class TestErrorRowPreservation:
+    def test_timeout_rows_counted_as_failed_with_nullable_slots(self, tmp_path: Path) -> None:
+        rows = [
+            _row(session_start=1, repeat=0, status="timeout", error="gpu hang"),
+            _row(session_start=1, repeat=1, status="ok"),
+        ]
+        input_path = _write_jsonl(tmp_path, rows)
+        summary = validate_and_aggregate(input_path)
+        assert summary["sample_counts"]["failed"] == 1
+        assert summary["sample_counts"]["successful"] == 1
+        # successful timings are only row[1]; all percentiles equal that row's values
+        assert summary["stage_percentiles_ms"]["totalRequestMs"]["p50"] == pytest.approx(11.75)
+
+
+# ---------------------------------------------------------------------------
+# Integrator regressions: v1 hard-pessimism, seed 0, partial error timings,
+# shape bounds
+# ---------------------------------------------------------------------------
+
+
+class TestIntegratorRegressions:
+    def test_unknown_semantics_still_false_process_cold(self, tmp_path: Path) -> None:
+        rows = [_row(session_start=1, repeat=0)]
+        rows[0]["provenance"]["session_start_semantics"] = "totally_unknown_semantic_XYZ"
+        input_path = _write_jsonl(tmp_path, rows)
+        summary = validate_and_aggregate(input_path)
+        assert summary["process_cold_claimable"] is False
+        assert summary["experimental_condition"]["provenance"]["session_start_semantics"] == "totally_unknown_semantic_XYZ"
+        assert "always False regardless of semantics string" in summary["process_cold_note"]
+
+    def test_matching_provider_unverified_evidence_not_proven(self, tmp_path: Path) -> None:
+        rows = [_row(session_start=1, repeat=0, observed_provider="wasm")]
+        rows[0]["requested_provider"] = "wasm"
+        rows[0]["observed_provider"] = "wasm"
+        rows[0]["provenance"]["execution_provider_evidence"] = "raw browser string: wasm observed"
+        input_path = _write_jsonl(tmp_path, rows)
+        summary = validate_and_aggregate(input_path)
+        assert summary["requested_is_proven"] is False
+        assert summary["experimental_condition"]["requested_provider"] == "wasm"
+        assert summary["experimental_condition"]["observed_provider"] == "wasm"
+        assert summary["experimental_condition"]["provenance"]["execution_provider_evidence"] == "raw browser string: wasm observed"
+        assert "no structured verified execution artifact" in summary["provider_claim_note"]
+
+    def test_seed_zero_is_valid(self, tmp_path: Path) -> None:
+        rows = _build_120row_fixture()
+        for row in rows:
+            row["seed"] = 0
+        input_path = _write_jsonl(tmp_path, rows)
+        summary = validate_and_aggregate(input_path)
+        assert summary["sample_counts"]["successful"] == 120
+        assert summary["experimental_condition"]["candidate_count"] == 4
+        p50 = summary["stage_percentiles_ms"]["totalRequestMs"]["p50"]
+        assert p50 == pytest.approx(60.5)
+
+    def test_partial_measured_error_row_validated_and_excluded_from_percentiles(self, tmp_path: Path) -> None:
+        rows = _build_120row_fixture()
+        error_row = _row(
+            session_start=11,
+            repeat=0,
+            case_id="case-extra-error",
+            status="error",
+            error="inference timeout after prepare",
+            timings={
+                "tokenizeMs": 12.0,
+                "prepareFeedMs": 5.5,
+                "totalRequestMs": 500.0,
+            },
+        )
+        rows.append(error_row)
+        input_path = _write_jsonl(tmp_path, rows)
+        summary = validate_and_aggregate(input_path)
+        assert summary["sample_counts"]["successful"] == 120
+        assert summary["sample_counts"]["failed"] == 1
+        p50 = summary["stage_percentiles_ms"]["totalRequestMs"]["p50"]
+        p95 = summary["stage_percentiles_ms"]["totalRequestMs"]["p95"]
+        assert p50 == pytest.approx(60.5)
+        assert p95 == pytest.approx(114.05)
+
+    def test_shape_candidate_exceeds_padded_rejected(self) -> None:
+        row = _row(candidate_count=10, padded_option_slots=8)
+        with pytest.raises(ValueError, match="candidate_count must be <= padded_option_slots"):
+            _validate_row(row, 1)
+
+    def test_shape_padded_exceeds_32_rejected(self) -> None:
+        row = _row(candidate_count=16, padded_option_slots=33)
+        with pytest.raises(ValueError, match="padded_option_slots must be <= 32"):
+            _validate_row(row, 1)
+
+    def test_shape_sequence_exceeds_512_rejected(self) -> None:
+        row = _row(sequence_length=513)
+        with pytest.raises(ValueError, match="sequence_length must be <= 512"):
+            _validate_row(row, 1)
+
+    def test_shape_boundary_values_accepted(self) -> None:
+        row = _row(candidate_count=32, padded_option_slots=32, sequence_length=512)
+        _validate_row(row, 1)
+
+
+# ---------------------------------------------------------------------------
+# --report-input mode: normalize live_candidates/allocated_candidates/
+# sequence_tokens from existing v1 browser-benchmark JSON report, preserve
+# top-level provenance, and never invent missing values
+# ---------------------------------------------------------------------------
+
+
+def _build_v1_report_fixture(
+    *,
+    backend: str = "direct",
+    live_field_name: str = "live_candidates",
+    allocated_field_name: str = "allocated_candidates",
+    seq_field_name: str = "sequence_length",
+    top_level_ort: str | None = "1.20.1",
+    include_session_start_semantics: bool = True,
+    include_environment: bool = True,
+    extra_failures: int = 0,
+) -> dict[str, Any]:
+    samples: list[dict[str, Any]] = []
+    counter = 0
+    for session in range(1, 11):
+        for repeat in range(12):
+            counter += 1
+            if extra_failures > 0 and counter % 15 == 0:
+                sample: dict[str, Any] = {
+                    "run_id": "run-alpha",
+                    "session_start": session,
+                    "repeat": repeat,
+                    "case_id": f"case-{counter}",
+                    "backend": backend,
+                    "requested_provider": "wasm",
+                    "observed_provider": "wasm",
+                    "bundle_hash": SHA_A,
+                    "tokenizer_hash": SHA_B,
+                    "input_hash": SHA_C,
+                    "noise_hash": None,
+                    live_field_name: 4,
+                    allocated_field_name: 8,
+                    seq_field_name: 64,
+                    "seed": 42,
+                    "ort_version": top_level_ort,
+                    "status": "error",
+                    "error": "simulated",
+                    "tokenizeMs": None,
+                    "prepareFeedMs": None,
+                    "inferenceAndReadbackMs": None,
+                    "postprocessMs": None,
+                    "totalRequestMs": None,
+                }
+                if backend == "diffusion":
+                    sample["noise_hash"] = SHA_NOISE
+                samples.append(sample)
+                extra_failures -= 1
+            else:
+                total = float(counter)
+                tokenize = 0.1 * counter
+                prepare = 0.05 * counter
+                inference = 0.8 * counter
+                post = 0.05 * counter
+                sample = {
+                    "run_id": "run-alpha",
+                    "session_start": session,
+                    "repeat": repeat,
+                    "case_id": f"case-{counter}",
+                    "backend": backend,
+                    "requested_provider": "wasm",
+                    "observed_provider": "wasm",
+                    "bundle_hash": SHA_A,
+                    "tokenizer_hash": SHA_B,
+                    "input_hash": SHA_C,
+                    "noise_hash": None,
+                    live_field_name: 4,
+                    allocated_field_name: 8,
+                    seq_field_name: 64,
+                    "seed": 42,
+                    "ort_version": top_level_ort,
+                    "status": "ok",
+                    "error": None,
+                    "tokenizeMs": tokenize,
+                    "prepareFeedMs": prepare,
+                    "inferenceAndReadbackMs": inference,
+                    "postprocessMs": post,
+                    "totalRequestMs": total,
+                    "js_heap_used_bytes_before": 1000.0 + counter,
+                    "js_heap_used_bytes_after": 2000.0 + counter,
+                }
+                if backend == "diffusion":
+                    sample["noise_hash"] = SHA_NOISE
+                samples.append(sample)
+    report: dict[str, Any] = {
+        "schema": "vons.browser-benchmark/v1",
+        "run_id": "run-alpha",
+        "backend": backend,
+        "requested_provider": "wasm",
+        "warmup_excluded_per_session": 10,
+        "samples": samples,
+    }
+    if include_environment:
+        report["environment"] = dict(BASE_ENV)
+    report["execution_provider_evidence"] = "window.ort.env.backend='wasm'"
+    if include_session_start_semantics:
+        report["session_start_semantics"] = "page_reload"
+    if top_level_ort is not None:
+        report["ort_version"] = top_level_ort
+    return report
+
+
+def _write_report(tmp_path: Path, report: dict[str, Any], *, name: str = "report.json") -> Path:
+    path = tmp_path / name
+    path.write_text(json.dumps(report, indent=2, sort_keys=True), encoding="utf-8")
+    return path
+
+
+class TestReportInputNormalization:
+    def test_report_happy_path_matches_jsonl_percentiles(self, tmp_path: Path) -> None:
+        report = _build_v1_report_fixture()
+        report_path = _write_report(tmp_path, report)
+        summary = validate_and_aggregate_report(report_path)
+        assert summary["sample_counts"]["successful"] == 120
+        assert summary["sample_counts"]["failed"] == 0
+        assert summary["measurement_completeness"]["complete"] is True
+        p50 = summary["stage_percentiles_ms"]["totalRequestMs"]["p50"]
+        p95 = summary["stage_percentiles_ms"]["totalRequestMs"]["p95"]
+        assert p50 == pytest.approx(60.5)
+        assert p95 == pytest.approx(114.05)
+        assert summary["experimental_condition"]["provenance"]["session_start_semantics"] == "page_reload"
+        assert summary["process_cold_claimable"] is False
+        assert summary["requested_is_proven"] is False
+
+    def test_report_sequence_tokens_fallback_alias(self, tmp_path: Path) -> None:
+        report = _build_v1_report_fixture(seq_field_name="sequence_tokens")
+        for sample in report["samples"]:
+            assert "sequence_length" not in sample
+            assert sample["sequence_tokens"] == 64
+        report_path = _write_report(tmp_path, report)
+        summary = validate_and_aggregate_report(report_path)
+        assert summary["experimental_condition"]["sequence_length"] == 64
+        assert summary["stage_percentiles_ms"]["totalRequestMs"]["p50"] == pytest.approx(60.5)
+
+    def test_report_missing_live_candidates_rejected(self, tmp_path: Path) -> None:
+        report = _build_v1_report_fixture()
+        for sample in report["samples"]:
+            del sample["live_candidates"]
+        report_path = _write_report(tmp_path, report)
+        with pytest.raises(ValueError, match="missing live_candidates"):
+            validate_and_aggregate_report(report_path)
+
+    def test_report_missing_allocated_candidates_rejected(self, tmp_path: Path) -> None:
+        report = _build_v1_report_fixture()
+        for sample in report["samples"]:
+            del sample["allocated_candidates"]
+        report_path = _write_report(tmp_path, report)
+        with pytest.raises(ValueError, match="missing allocated_candidates"):
+            validate_and_aggregate_report(report_path)
+
+    def test_report_missing_sequence_both_names_rejected(self, tmp_path: Path) -> None:
+        report = _build_v1_report_fixture()
+        for sample in report["samples"]:
+            del sample["sequence_length"]
+        report_path = _write_report(tmp_path, report)
+        with pytest.raises(ValueError, match="missing sequence_length"):
+            validate_and_aggregate_report(report_path)
+
+    def test_report_missing_session_start_semantics_rejected_no_invent(self, tmp_path: Path) -> None:
+        report = _build_v1_report_fixture(include_session_start_semantics=False)
+        assert "session_start_semantics" not in report
+        report_path = _write_report(tmp_path, report)
+        with pytest.raises(ValueError, match="do not invent missing values"):
+            validate_and_aggregate_report(report_path)
+
+    def test_report_missing_ort_version_sample_and_top_rejected(self, tmp_path: Path) -> None:
+        report = _build_v1_report_fixture(top_level_ort=None)
+        for sample in report["samples"]:
+            del sample["ort_version"]
+        report_path = _write_report(tmp_path, report)
+        with pytest.raises(ValueError, match="missing ort_version"):
+            validate_and_aggregate_report(report_path)
+
+    def test_report_top_level_ort_used_as_fallback(self, tmp_path: Path) -> None:
+        report = _build_v1_report_fixture(top_level_ort="1.21.0-custom")
+        for sample in report["samples"]:
+            del sample["ort_version"]
+        report_path = _write_report(tmp_path, report)
+        summary = validate_and_aggregate_report(report_path)
+        assert summary["experimental_condition"]["ort_version"] == "1.21.0-custom"
+        assert summary["sample_counts"]["successful"] == 120
+
+    def test_report_wrong_schema_rejected(self, tmp_path: Path) -> None:
+        report = _build_v1_report_fixture()
+        report["schema"] = "other.schema/v2"
+        report_path = _write_report(tmp_path, report)
+        with pytest.raises(ValueError, match="unexpected browser benchmark schema"):
+            validate_and_aggregate_report(report_path)
+
+
+# ---------------------------------------------------------------------------
+# CLI --report-input subprocess paths
+# ---------------------------------------------------------------------------
+
+
+class TestCLIReportInput:
+    def test_cli_report_input_writes_summary(self, tmp_path: Path) -> None:
+        report = _build_v1_report_fixture()
+        report_path = _write_report(tmp_path, report)
+        output_path = tmp_path / "summary.json"
+        result = subprocess.run(
+            [
+                sys.executable,
+                str(SUMMARY_TOOL),
+                "--report-input",
+                str(report_path),
+                "--output",
+                str(output_path),
+            ],
+            capture_output=True,
+            check=False,
+            text=True,
+        )
+        assert result.returncode == 0, result.stderr
+        assert output_path.exists()
+        loaded = json.loads(output_path.read_text(encoding="utf-8"))
+        assert loaded["schema"] == "vons.browser-benchmark-summary/v1"
+        assert loaded["sample_counts"]["successful"] == 120
+        assert loaded["stage_percentiles_ms"]["totalRequestMs"]["p50"] == pytest.approx(60.5)
+        assert loaded["process_cold_claimable"] is False
+        assert loaded["requested_is_proven"] is False
+
+    def test_cli_mutually_exclusive_inputs(self, tmp_path: Path) -> None:
+        rows = _build_120row_fixture()
+        input_path = _write_jsonl(tmp_path, rows)
+        report = _build_v1_report_fixture()
+        report_path = _write_report(tmp_path, report)
+        output_path = tmp_path / "summary.json"
+        result = subprocess.run(
+            [
+                sys.executable,
+                str(SUMMARY_TOOL),
+                "--input",
+                str(input_path),
+                "--report-input",
+                str(report_path),
+                "--output",
+                str(output_path),
+            ],
+            capture_output=True,
+            check=False,
+            text=True,
+        )
+        assert result.returncode != 0
+        assert "not allowed with" in result.stderr or "argument --report-input: not allowed" in result.stderr
+
+
+# ---------------------------------------------------------------------------
+# Pass 3: Real report compatibility regressions — matches actual report
+# shape in reports/browser-direct-{wasm,webgpu-controlled}-merged.json:
+# - ort_version via top-level runtime_info.ortVersion (camelCase, nested)
+# - seed absent in samples => null allowed for direct backend when
+#   noise_hash=null (deterministic-direct not_applicable)
+# - observed_provider=null (harness doesn't expose execution partition)
+# - heap keys js_heap_used_bytes_before/after canonical
+# ---------------------------------------------------------------------------
+
+
+def _build_real_direct_report(
+    *,
+    runtime_ort: str = "1.30.0",
+    top_ort_version_key_present: bool = False,
+    top_ort_value: str | None = None,
+    seed_present_in_samples: bool = False,
+    noise_hash_value: None | str = None,
+) -> dict[str, Any]:
+    samples: list[dict[str, Any]] = []
+    counter = 0
+    for session in range(1, 7):
+        for repeat in range(20):
+            counter += 1
+            total = float(counter)
+            sample: dict[str, Any] = {
+                "run_id": "run-real-shape",
+                "session_start": session,
+                "repeat": repeat,
+                "case_id": f"case-{counter}",
+                "backend": "direct",
+                "requested_provider": "wasm",
+                "observed_provider": None,
+                "observed_provider_status": "session_created; execution_partition_not_exposed",
+                "bundle_hash": SHA_A,
+                "tokenizer_hash": SHA_B,
+                "input_hash": SHA_C,
+                "noise_hash": noise_hash_value,
+                "live_candidates": 4,
+                "allocated_candidates": 8,
+                "sequence_length": 64,
+                "status": "ok",
+                "error": None,
+                "tokenizeMs": 0.1 * counter,
+                "prepareFeedMs": 0.05 * counter,
+                "inferenceAndReadbackMs": 0.8 * counter,
+                "postprocessMs": 0.05 * counter,
+                "totalRequestMs": total,
+                "js_heap_used_bytes_before": 1000.0 + counter,
+                "js_heap_used_bytes_after": 2000.0 + counter,
+            }
+            if seed_present_in_samples:
+                sample["seed"] = 42
+            samples.append(sample)
+    report: dict[str, Any] = {
+        "schema": "vons.browser-benchmark/v1",
+        "run_id": "run-real-shape",
+        "backend": "direct",
+        "requested_provider": "wasm",
+        "environment": dict(BASE_ENV),
+        "execution_provider_evidence": "requested provider and session creation only",
+        "session_start_semantics": "one fresh page/session per source report; browser caches may persist",
+        "warmup_excluded_per_session": 10,
+        "runtime_info": {
+            "ortVersion": runtime_ort,
+            "provider": "wasm",
+            "wasmNumThreads": 1,
+            "webgpuAdapterRequested": False,
+            "webgpuDeviceRequested": False,
+        },
+        "samples": samples,
+    }
+    if top_ort_version_key_present:
+        report["ort_version"] = top_ort_value
+    return report
+
+
+class TestRealReportCompatibility:
+    def test_runtime_info_ortversion_used_as_top_fallback(self, tmp_path: Path) -> None:
+        report = _build_real_direct_report(runtime_ort="1.30.0-fromRuntimeInfo")
+        report_path = _write_report(tmp_path, report)
+        summary = validate_and_aggregate_report(report_path)
+        assert summary["experimental_condition"]["ort_version"] == "1.30.0-fromRuntimeInfo"
+        assert summary["sample_counts"]["successful"] == 120
+        p50 = summary["stage_percentiles_ms"]["totalRequestMs"]["p50"]
+        assert p50 == pytest.approx(60.5)
+
+    def test_top_ort_version_preferred_over_runtime_info(self, tmp_path: Path) -> None:
+        report = _build_real_direct_report(
+            runtime_ort="1.30.0-runtime-should-not-be-used",
+            top_ort_version_key_present=True,
+            top_ort_value="1.31.0-topPreferred",
+        )
+        report_path = _write_report(tmp_path, report)
+        summary = validate_and_aggregate_report(report_path)
+        assert summary["experimental_condition"]["ort_version"] == "1.31.0-topPreferred"
+
+    def test_missing_both_ort_raises_mentions_runtimeinfo(self, tmp_path: Path) -> None:
+        report = _build_real_direct_report(runtime_ort="1.30.0")
+        del report["runtime_info"]
+        report_path = _write_report(tmp_path, report)
+        with pytest.raises(ValueError, match="runtime_info.ortVersion"):
+            validate_and_aggregate_report(report_path)
+
+    def test_direct_samples_no_seed_noisehash_null_resolves_seed_null(self, tmp_path: Path) -> None:
+        report = _build_real_direct_report(seed_present_in_samples=False, noise_hash_value=None)
+        for sample in report["samples"]:
+            assert "seed" not in sample
+            assert sample["noise_hash"] is None
+        report_path = _write_report(tmp_path, report)
+        summary = validate_and_aggregate_report(report_path)
+        assert summary["experimental_condition"]["seed"] is None
+        assert summary["sample_counts"]["successful"] == 120
+        p50 = summary["stage_percentiles_ms"]["totalRequestMs"]["p50"]
+        assert p50 == pytest.approx(60.5)
+
+    def test_direct_with_noise_hash_still_requires_seed_not_null(self, tmp_path: Path) -> None:
+        report = _build_real_direct_report(seed_present_in_samples=False, noise_hash_value=SHA_NOISE)
+        for sample in report["samples"]:
+            assert "seed" not in sample
+            assert sample["noise_hash"] == SHA_NOISE
+        report_path = _write_report(tmp_path, report)
+        with pytest.raises(ValueError, match="missing seed"):
+            validate_and_aggregate_report(report_path)
+
+    def test_diffusion_samples_require_seed_never_null(self) -> None:
+        row = _row(backend="diffusion", noise_hash=SHA_NOISE)
+        row["seed"] = None
+        with pytest.raises(ValueError, match="seed may only be null for direct backend"):
+            _validate_row(row, 1)
+
+    def test_direct_with_seed_integer_still_accepted(self) -> None:
+        row = _row(seed=17)
+        row["noise_hash"] = None
+        row["seed"] = 17
+        _validate_row(row, 1)
+
+    def test_direct_seed_null_noise_hash_null_accepted_at_row_level(self) -> None:
+        row = _row(seed=42)
+        row["seed"] = None
+        row["noise_hash"] = None
+        _validate_row(row, 1)
+
+    def test_observed_provider_null_preserved_in_summary(self, tmp_path: Path) -> None:
+        report = _build_real_direct_report()
+        report_path = _write_report(tmp_path, report)
+        summary = validate_and_aggregate_report(report_path)
+        assert summary["experimental_condition"]["observed_provider"] is None
+        assert summary["requested_is_proven"] is False
+
+    def test_heap_keys_canonical_and_values_match(self, tmp_path: Path) -> None:
+        report = _build_real_direct_report()
+        report_path = _write_report(tmp_path, report)
+        summary = validate_and_aggregate_report(report_path)
+        keys = sorted(summary["heap_maxima_bytes"].keys())
+        assert keys == ["js_heap_used_bytes_after", "js_heap_used_bytes_before"]
+        # counter = 1..120 => heap_before = 1000 + counter => max=1120
+        assert summary["heap_maxima_bytes"]["js_heap_used_bytes_before"] == pytest.approx(1120.0)
+        assert summary["heap_maxima_bytes"]["js_heap_used_bytes_after"] == pytest.approx(2120.0)
+
+    def test_completeness_passes_with_real_reports_120(self, tmp_path: Path) -> None:
+        report = _build_real_direct_report()
+        report_path = _write_report(tmp_path, report)
+        summary = validate_and_aggregate_report(report_path)
+        assert summary["measurement_completeness"]["complete"] is True
+        assert summary["measurement_completeness"]["incomplete_reasons"] == []
+        assert summary["sample_counts"]["unique_session_starts"] == 6

tests/test_browser_parity_reference.py

@@ -0,0 +1,350 @@
+"""Verifier regressions with tiny tokenizers and mocked CPU outputs only."""
+
+import copy
+import hashlib
+import importlib.util
+import json
+import math
+from pathlib import Path
+from types import SimpleNamespace
+
+import numpy as np
+import pytest
+
+SPEC = importlib.util.spec_from_file_location(
+    "browser_parity_reference", Path(__file__).parents[1] / "tools/verify_browser_parity.py"
+)
+assert SPEC is not None and SPEC.loader is not None
+verifier = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(verifier)
+
+
+class TinyTokenizer:
+    def encode(self, text):
+        ids = [101, *text.encode("utf-8"), 102]
+        return SimpleNamespace(ids=ids, attention_mask=[1] * len(ids), type_ids=[0] * len(ids))
+
+    def token_to_id(self, token):
+        assert token == "[PAD]"
+        return 0
+
+
+class Reference:
+    def __init__(self):
+        self.feeds = []
+        self.answerability = 2.0
+        self.invalid = False
+
+    def run(self, feed, backend):
+        self.feeds.append(copy.deepcopy(feed))
+        scores = np.zeros(feed["option_mask"].shape, np.float32)
+        scores[0, 0] = float("nan") if self.invalid else 3.0
+        return scores, np.array([self.answerability], np.float32)
+
+
+def question(key="q", kind="choice"):
+    return {"id": key, "type": kind, "prompt": "Choose", "options": ["first", "second"]}
+
+
+def expected_answer(q, logit=2.0):
+    options = q["options"] or ["true", "false"]
+    probability = 1 / (1 + math.exp(-3))
+    answerability = 1 / (1 + math.exp(-logit))
+    confidence = probability * answerability
+    reason = "answerability_below_threshold" if answerability < 0.5 else (
+        "confidence_below_threshold" if confidence < 0.55 else None
+    )
+    return {"question_id": q["id"], "choice": None if reason else options[0],
+            "probabilities": [{"option": options[0], "probability": probability},
+                              {"option": options[1], "probability": 1 - probability}],
+            "confidence": confidence, "status": "abstain" if reason else "ok",
+            "abstain_reason": reason}
+
+
+def fixture(backend="direct", multi=False):
+    questions = [question()]
+    if multi:
+        questions.append({"id": "q2", "type": "boolean", "prompt": "Continue?", "options": []})
+    request = {"state": "ready", "questions": questions, "seed": 7}
+    metadata = {"backend": backend, "sequence_length": 128, "option_count": 4}
+    manifest = {"metadata": metadata}
+    noise = [0.25, -0.5, 1.0, 2.0] if backend == "diffusion" else None
+    traces, timings, answers = [], [], []
+    for q in questions:
+        options = q["options"] or ["true", "false"]
+        slots = 4 if backend == "diffusion" else 2
+        ids, masks, types, live = [], [], [], 0
+        for index in range(slots):
+            raw = [101, *f"ready\nQuestion: {q['prompt']}\nCandidate: {options[index]}".encode(), 102] \
+                if index < 2 else []
+            live += len(raw)
+            ids.extend(raw + [0] * (128 - len(raw)))
+            masks.extend([1] * len(raw) + [0] * (128 - len(raw)))
+            types.extend([0] * 128)
+        answer = expected_answer(q)
+        traces.append({"questionId": q["id"], "inputIds": ids, "attentionMask": masks,
+                       "tokenTypeIds": types, "optionMask": [1, 1] + [0] * (slots - 2),
+                       "initialNoise": noise, "rawScores": [3.0, 0.0], "answerabilityLogit": 2.0,
+                       "probabilities": [p["probability"] for p in answer["probabilities"]],
+                       "answer": copy.deepcopy(answer)})
+        timings.append({"questionId": q["id"], "live_candidates": 2, "allocated_candidates": slots,
+                        "live_tokens": live, "sequence_length": 128})
+        answers.append(answer)
+    row = {"fixture_id": "fixture", "input_hash": verifier.request_hash(request),
+           "request": request, "status": "ok", "traces": traces, "timings": timings,
+           "response": {"backend": backend, "model_id": f"vons-{backend}-onnx-web",
+                        "answers": answers}}
+    report = {"schema": verifier.SCHEMA, "backend": backend, "fixture_count": 1,
+              "noise_values": noise, "records": [row]}
+    return report, manifest
+
+
+def run(report, manifest, reference=None):
+    return verifier.verify_records(report, manifest, TinyTokenizer(), reference or Reference())
+
+
+def test_canonical_hash_matches_browser_fixture_domain_and_unicode_values():
+    value = {"state": {"z": "🌐 검토", "a": 2}, "seed": 7, "questions": []}
+    canonical = '{"questions":[],"seed":7,"state":{"a":2,"z":"🌐 검토"}}'
+    assert verifier.stable_json(value) == canonical
+    assert verifier.request_hash(value) == hashlib.sha256(canonical.encode()).hexdigest()
+    assert verifier.stable_json({"seed": -0.0}) == '{"seed":0}'
+
+
+@pytest.mark.parametrize("value", [{"Mixed": 1}, {"a_b": 1}, {"é": 1}, {"a": 1.25},
+                                   {"a": 2**53}, {"a": float("nan")}])
+def test_unsupported_json_canonicalization_fails_closed(value):
+    with pytest.raises(verifier.ParityError):
+        verifier.stable_json(value)
+
+
+@pytest.mark.parametrize("backend", ["direct", "diffusion"])
+def test_every_multiquestion_trace_and_response_compares(backend):
+    report, manifest = fixture(backend, multi=True)
+    reference = Reference()
+    result = run(report, manifest, reference)
+    assert result["counts"] == {"passed": 1, "failed": 0, "unverified": 0,
+                               "contract_error_verified": 0}
+    assert result["numerical_questions"] == {"passed": 2, "failed": 0}
+    assert result["all_numerical_comparisons_passed"]
+    assert len(reference.feeds) == 2
+    assert result["calibration"] is None
+    if backend == "diffusion":
+        expected = hashlib.sha256(np.array(report["noise_values"], dtype="<f4").tobytes()).hexdigest()
+        assert all(q["noise_float32_le_sha256"] == expected for q in result["records"][0]["questions"])
+        np.testing.assert_array_equal(reference.feeds[0]["initial_noise"], [[0.25, -0.5, 1, 2]])
+
+
+@pytest.mark.parametrize("field", ["inputIds", "attentionMask", "tokenTypeIds", "optionMask"])
+def test_exact_token_arrays_are_required_before_inference(field):
+    report, manifest = fixture()
+    report["records"][0]["traces"][0][field][0] += 1
+    reference = Reference()
+    result = run(report, manifest, reference)
+    assert result["counts"]["failed"] == 1
+    assert not reference.feeds
+    assert field in result["records"][0]["questions"][0]["reason"]
+
+
+@pytest.mark.parametrize("mutation", ["missing_trace", "missing_hash", "bad_hash", "missing_question",
+                                     "wrong_shape", "response_choice", "response_probability"])
+def test_missing_or_tampered_evidence_cannot_pass(mutation):
+    report, manifest = fixture(multi=True)
+    row = report["records"][0]
+    if mutation == "missing_trace":
+        row["traces"] = []
+    elif mutation == "missing_hash":
+        del row["input_hash"]
+    elif mutation == "bad_hash":
+        row["input_hash"] = "0" * 64
+    elif mutation == "missing_question":
+        row["response"]["answers"].pop()
+    elif mutation == "wrong_shape":
+        row["timings"][0]["sequence_length"] = 512
+    elif mutation == "response_choice":
+        row["response"]["answers"][1]["choice"] = "false"
+    else:
+        row["response"]["answers"][1]["probabilities"][0]["probability"] = 0.1
+    result = run(report, manifest)
+    assert result["counts"]["failed"] == 1
+    assert not result["all_numerical_comparisons_passed"]
+
+
+@pytest.mark.parametrize("field", ["rawScores", "probabilities", "answerabilityLogit"])
+def test_nonfinite_browser_values_never_pass(field):
+    report, manifest = fixture()
+    trace = report["records"][0]["traces"][0]
+    trace[field] = float("nan") if field == "answerabilityLogit" else [float("nan"), 0.0]
+    result = run(report, manifest)
+    assert result["counts"]["failed"] == 1
+
+
+def test_nonfinite_cpu_values_never_pass_even_with_large_tolerance():
+    report, manifest = fixture()
+    reference = Reference()
+    reference.invalid = True
+    result = verifier.verify_records(report, manifest, TinyTokenizer(), reference, atol=100, rtol=100)
+    assert result["counts"]["failed"] == 1
+    assert "non-finite" in result["records"][0]["questions"][0]["reason"]
+
+
+def test_noise_uses_array_identity_not_seed_identity():
+    report, manifest = fixture("diffusion")
+    report["records"][0]["traces"][0]["initialNoise"] = [0.5, -0.5, 1.0, 2.0]
+    reference = Reference()
+    result = run(report, manifest, reference)
+    assert result["counts"]["failed"] == 1
+    assert not reference.feeds
+
+
+def test_non_float32_noise_fails_before_inference():
+    report, manifest = fixture("diffusion")
+    report["noise_values"][0] = 0.1
+    result = run(report, manifest)
+    assert "exact Float32" in result["records"][0]["questions"][0]["reason"]
+
+
+def test_postprocess_both_abstention_gates_and_tie_order():
+    answer = verifier.postprocess([4.0, 0.0], -1.0, ["first", "second"], "q")
+    assert answer["abstain_reason"] == "answerability_below_threshold" and answer["choice"] is None
+    answer = verifier.postprocess([0.0, 0.0], 20.0, ["first", "second"], "q")
+    assert answer["abstain_reason"] == "confidence_below_threshold" and answer["choice"] is None
+    answer = verifier.postprocess([3.0, 0.0], 2.0, ["first", "second"], "q")
+    assert answer["choice"] == "first" and answer["status"] == "ok"
+    with pytest.raises(verifier.ParityError):
+        verifier.postprocess([-math.inf, -math.inf], 2, ["first", "second"], "q")
+
+
+def test_score_unsupported_is_unverified_not_contract_or_numerical_pass():
+    report, manifest = fixture()
+    row = report["records"][0]
+    row["request"]["questions"][0].update(type="score", rubric=["poor", "good"])
+    row["input_hash"] = verifier.request_hash(row["request"])
+    row.update(status="expected_error", traces=[], timings=[],
+               error="Error: score questions are not supported by this candidate-selection ONNX head")
+    result = run(report, manifest)
+    assert result["counts"]["unverified"] == 1
+    assert result["numerical_questions"] == {"passed": 0, "failed": 0}
+    assert not result["all_numerical_comparisons_passed"]
+    assert not result["complete_contract_verified"]
+
+
+def test_expected_overflow_requires_independent_exact_tokenization():
+    report, manifest = fixture()
+    row = report["records"][0]
+    row.update(status="expected_error", traces=[], timings=[], error="RangeError: token overflow")
+    assert run(report, manifest)["counts"]["failed"] == 1
+    row["request"]["state"] = "x" * 200
+    row["input_hash"] = verifier.request_hash(row["request"])
+    result = run(report, manifest)
+    assert result["counts"]["contract_error_verified"] == 1
+    assert result["numerical_questions"]["passed"] == 0
+    assert not result["all_numerical_comparisons_passed"]
+
+
+def test_aggregate_budget_can_overflow_when_individual_candidates_fit():
+    q = question()
+    q["options"] = ["x" * 60, "y" * 60]
+    with pytest.raises(verifier.InputOverflow, match="aggregate"):
+        verifier.build_inputs(TinyTokenizer(), "ready", q,
+                              {"sequence_length": 128, "option_count": 32}, "direct")
+
+
+def test_empty_duplicate_and_inconsistent_fixture_sets_fail():
+    report, manifest = fixture()
+    duplicate = copy.deepcopy(report["records"][0])
+    report["records"].append(duplicate)
+    report["fixture_count"] = 2
+    assert run(report, manifest)["counts"]["failed"] == 1
+    report["fixture_count"] = 3
+    with pytest.raises(verifier.ParityError, match="fixture_count"):
+        run(report, manifest)
+    report.update(records=[], fixture_count=0)
+    with pytest.raises(verifier.ParityError, match="nonempty"):
+        run(report, manifest)
+
+
+def make_artifacts(tmp_path):
+    root = tmp_path / "bundle"
+    root.mkdir()
+    graph, tokenizer = root / "model.onnx", root / "tokenizer.json"
+    graph.write_bytes(b"mock graph; no ORT load")
+    tokenizer.write_text("{}")
+    records = [{"path": path.name, "bytes": path.stat().st_size,
+                "sha256": verifier.file_hash(path), "role": role}
+               for path, role in [(graph, "model_graph"), (tokenizer, "tokenizer")]]
+    manifest_path = root / "bundle-manifest-v1.json"
+    manifest_path.write_text(json.dumps({"schema_version": "vons.bundle.manifest/v1",
+                                         "metadata": {"backend": "direct"}, "files": records}))
+    report = {"schema": verifier.SCHEMA, "backend": "direct",
+              "requested_provider": "wasm",
+              "manifest_hash": verifier.file_hash(manifest_path),
+              "tokenizer_hash": verifier.file_hash(tokenizer)}
+    return root, report, manifest_path
+
+
+def test_artifact_identity_pinned_before_reference_loading(tmp_path, monkeypatch):
+    root, report, manifest_path = make_artifacts(tmp_path)
+    calls = []
+    monkeypatch.setattr(verifier, "verify_bundle_manifest", lambda path: calls.append(path) or {"pass": True})
+    artifacts = verifier.validate_artifacts(report, manifest_path)
+    assert calls == [manifest_path]
+    assert artifacts["graph"] == root / "model.onnx"
+    report["manifest_hash"] = "0" * 64
+    with pytest.raises(verifier.ParityError, match="manifest_hash"):
+        verifier.validate_artifacts(report, manifest_path)
+    assert calls == [manifest_path]
+
+
+@pytest.mark.parametrize("mutation", ["missing_hash", "tokenizer_hash", "mutated_file", "missing_file"])
+def test_missing_and_changed_artifacts_fail(tmp_path, monkeypatch, mutation):
+    root, report, path = make_artifacts(tmp_path)
+    monkeypatch.setattr(verifier, "verify_bundle_manifest", lambda path: {"pass": True})
+    if mutation == "missing_hash":
+        del report["manifest_hash"]
+    elif mutation == "tokenizer_hash":
+        report["tokenizer_hash"] = "0" * 64
+    elif mutation == "mutated_file":
+        (root / "model.onnx").write_bytes(b"tampered")
+    else:
+        (root / "model.onnx").unlink()
+    with pytest.raises(verifier.ParityError):
+        verifier.validate_artifacts(report, path)
+
+
+@pytest.mark.parametrize("relative", ["../outside", "/absolute", "C:/drive", "https:remote", "x\\y"])
+def test_manifest_path_escape_rejected(tmp_path, relative):
+    with pytest.raises(verifier.ParityError):
+        verifier._relative_file(tmp_path, relative)
+
+
+def test_symlink_parent_even_inside_bundle_rejected(tmp_path):
+    real = tmp_path / "real"
+    real.mkdir()
+    (real / "data").write_bytes(b"data")
+    (tmp_path / "linked").symlink_to(real, target_is_directory=True)
+    with pytest.raises(verifier.ParityError, match="symlink"):
+        verifier._relative_file(tmp_path, "linked/data")
+
+
+def test_json_duplicate_keys_and_nan_rejected(tmp_path):
+    path = tmp_path / "invalid.json"
+    for payload in ('{"x":1,"x":2}', '{"x":NaN}'):
+        path.write_text(payload)
+        with pytest.raises(verifier.ParityError):
+            verifier.read_json(path)
+
+
+def test_existing_evidence_is_not_overwritten_or_loaded(tmp_path):
+    output = tmp_path / "evidence.json"
+    output.write_text("preserved")
+    with pytest.raises(FileExistsError, match="overwrite"):
+        verifier.verify_report(tmp_path / "missing-report", tmp_path / "missing-manifest", output)
+    assert output.read_text() == "preserved"
+
+
+@pytest.mark.parametrize("atol,rtol", [(math.nan, 1e-5), (1e-5, math.inf), (-1, 0)])
+def test_invalid_tolerances_rejected(atol, rtol):
+    report, manifest = fixture()
+    with pytest.raises(verifier.ParityError, match="tolerances"):
+        verifier.verify_records(report, manifest, TinyTokenizer(), Reference(), atol, rtol)

tests/test_bundle.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from vons.bundle import (
+    BundleManifestError,
+    _snapshot_hash,
+    build_bundle_manifest,
+    verify_bundle_manifest,
+)
+
+
+def _write_external_model(root: Path) -> tuple[Path, Path]:
+    onnx = pytest.importorskip("onnx")
+    from onnx import TensorProto, helper, numpy_helper
+
+    root.mkdir(parents=True, exist_ok=True)
+    initializer = numpy_helper.from_array(__import__("numpy").ones(2048, dtype="float32"), name="weight")
+    graph = helper.make_graph(
+        [helper.make_node("Identity", ["input"], ["output"])],
+        "test",
+        [helper.make_tensor_value_info("input", TensorProto.FLOAT, [2])],
+        [helper.make_tensor_value_info("output", TensorProto.FLOAT, [2])],
+        [initializer],
+    )
+    model = helper.make_model(graph, opset_imports=[helper.make_opsetid("", 18)])
+    graph_path = root / "model.onnx"
+    onnx.save_model(model, graph_path, save_as_external_data=True, all_tensors_to_one_file=True, location="weights.onnx.data")
+    tokenizer = root / "tokenizer"
+    tokenizer.mkdir()
+    (tokenizer / "tokenizer.json").write_text("{}\n", encoding="utf-8")
+    return graph_path, tokenizer
+
+
+def test_manifest_inventories_external_data_and_verifies_bytes(tmp_path: Path) -> None:
+    graph, tokenizer = _write_external_model(tmp_path)
+    output = tmp_path / "bundle-manifest.v1.json"
+    build_bundle_manifest(graph, tokenizer, output)
+    result = verify_bundle_manifest(output)
+    payload = json.loads(output.read_text(encoding="utf-8"))
+
+    assert result["pass"] is True
+    assert result["external_data_files"] == 1
+    assert {item["role"] for item in payload["files"]} >= {"model_graph", "model_external_data", "tokenizer"}
+    assert payload["summary"]["model_asset_bytes"] == sum(
+        item["bytes"] for item in payload["files"] if item["model_asset"]
+    )
+
+    external = tmp_path / "weights.onnx.data"
+    external.write_bytes(external.read_bytes() + b"changed")
+    with pytest.raises(BundleManifestError, match="changed"):
+        verify_bundle_manifest(output)
+
+
+def test_manifest_rejects_missing_external_data_and_empty_tokenizer(tmp_path: Path) -> None:
+    graph, tokenizer = _write_external_model(tmp_path)
+    (tmp_path / "weights.onnx.data").unlink()
+    with pytest.raises(BundleManifestError, match="external-data file does not exist"):
+        build_bundle_manifest(graph, tokenizer, tmp_path / "manifest.json")
+
+    graph, tokenizer = _write_external_model(tmp_path / "second")
+    for child in tokenizer.iterdir():
+        child.unlink()
+    with pytest.raises(BundleManifestError, match="contains no regular files"):
+        build_bundle_manifest(graph, tokenizer, tokenizer.parent / "manifest.json")
+
+
+def test_manifest_rejects_external_data_traversal(tmp_path: Path) -> None:
+    onnx = pytest.importorskip("onnx")
+    from onnx import TensorProto, helper
+
+    initializer = helper.make_tensor("weight", TensorProto.FLOAT, [1], [1.0])
+    initializer.data_location = TensorProto.EXTERNAL
+    initializer.external_data.add(key="location", value="../outside.onnx.data")
+    graph = helper.make_graph([], "test", [], [], [initializer])
+    model = helper.make_model(graph, opset_imports=[helper.make_opsetid("", 18)])
+    graph_path = tmp_path / "model.onnx"
+    onnx.save_model(model, graph_path)
+    tokenizer = tmp_path / "tokenizer"
+    tokenizer.mkdir()
+    (tokenizer / "tokenizer.json").write_text("{}\n", encoding="utf-8")
+
+    with pytest.raises(BundleManifestError, match="traversal"):
+        build_bundle_manifest(graph_path, tokenizer, tmp_path / "manifest.json")
+
+
+def test_manifest_rejects_symlinked_tokenizer(tmp_path: Path) -> None:
+    graph, tokenizer = _write_external_model(tmp_path)
+    target = tmp_path / "outside.txt"
+    target.write_text("outside", encoding="utf-8")
+    (tokenizer / "escape.txt").symlink_to(target)
+
+    with pytest.raises(BundleManifestError, match="symlink"):
+        build_bundle_manifest(graph, tokenizer, tmp_path / "manifest.json")
+
+
+def test_source_snapshot_ignores_generated_python_caches(tmp_path: Path) -> None:
+    source = tmp_path / "source"
+    source.mkdir()
+    (source / "module.py").write_text("value = 1\n", encoding="utf-8")
+    ignored = source / "__pycache__"
+    ignored.mkdir()
+    (ignored / "module.cpython-313.pyc").write_bytes(b"first")
+    first = _snapshot_hash(source)
+    (ignored / "module.cpython-313.pyc").write_bytes(b"second")
+    (source / ".pytest_cache").mkdir()
+    (source / ".pytest_cache" / "state").write_bytes(b"cache")
+    assert _snapshot_hash(source) == first
+
+
+def test_source_snapshot_can_pin_an_explicit_file_list(tmp_path: Path) -> None:
+    source = tmp_path / "source"
+    source.mkdir()
+    (source / "module.py").write_text("value = 1\n", encoding="utf-8")
+    (source / "config.json").write_text("{}\n", encoding="utf-8")
+
+    first = _snapshot_hash(source, ["module.py"])
+    assert first["scope"] == "explicit"
+    assert first["paths"] == ["module.py"]
+    (source / "config.json").write_text('{"changed": true}\n', encoding="utf-8")
+    assert _snapshot_hash(source, ["module.py"]) == first
+    (source / "module.py").write_text("value = 2\n", encoding="utf-8")
+    assert _snapshot_hash(source, ["module.py"]) != first
+
+
+def test_source_snapshot_rejects_explicit_paths_outside_root(tmp_path: Path) -> None:
+    source = tmp_path / "source"
+    source.mkdir()
+    outside = tmp_path / "outside.py"
+    outside.write_text("value = 1\n", encoding="utf-8")
+
+    with pytest.raises(BundleManifestError, match="escapes"):
+        _snapshot_hash(source, [outside])

tests/test_calibration.py

@@ -0,0 +1,241 @@
+import hashlib
+import json
+import math
+import tempfile
+import unittest
+from pathlib import Path
+
+from vons.calibration import (
+    ABSTAIN_ALL_THRESHOLD,
+    CALIBRATION_VERSION,
+    apply_calibration,
+    calibrate_report,
+    fit_abstention_threshold,
+    fit_abstention_threshold_details,
+    fit_temperature,
+    fit_temperature_details,
+)
+from vons.data import Example, write_jsonl
+from vons.evaluation import METRIC_VERSION, Prediction, nll, summarize, write_report
+
+
+def _example(identifier: str, label: str | None, answerable: bool, split: str = "calibration") -> Example:
+    return Example(
+        id=identifier,
+        task_group="calibration",
+        state="state",
+        question="choose",
+        options=("a", "b"),
+        label=label,
+        answerable=answerable,
+        split=split,
+        provenance={},
+        metadata={"scenario_id": identifier},
+    )
+
+
+def _reject_constant(value: str) -> float:
+    raise ValueError(f"non-strict JSON constant {value}")
+
+
+class CalibrationTests(unittest.TestCase):
+    def test_temperature_fit_finds_interior_optimum_and_does_not_increase_nll(self) -> None:
+        examples = [_example(f"r{index}", "a" if index < 3 else "b", True) for index in range(4)]
+        predictions = [Prediction(f"r{index}", "a", {"a": 0.6, "b": 0.4}, 0.6, False) for index in range(4)]
+
+        details = fit_temperature_details(examples, predictions)
+        calibrated = apply_calibration(examples, predictions, temperature=details.temperature, abstention_threshold=0.0)
+
+        self.assertAlmostEqual(details.temperature, math.log(1.5) / math.log(3.0), places=6)
+        self.assertEqual(details.rows, 4)
+        self.assertFalse(details.at_lower_bound)
+        self.assertFalse(details.at_upper_bound)
+        self.assertEqual(fit_temperature(examples, predictions), details.temperature)
+        self.assertLess(nll(examples, calibrated), nll(examples, predictions))
+
+    def test_temperature_bound_hit_is_flagged(self) -> None:
+        examples = [_example(f"s{index}", "a", True) for index in range(4)]
+        predictions = [Prediction(f"s{index}", "a", {"a": 0.9, "b": 0.1}, 0.9, False) for index in range(4)]
+
+        details = fit_temperature_details(examples, predictions)
+
+        self.assertTrue(details.at_lower_bound)
+        self.assertAlmostEqual(details.temperature, 0.05)
+
+    def test_temperature_scaling_preserves_true_zero_support(self) -> None:
+        examples = [_example("zero", "a", True)]
+        predictions = [Prediction("zero", "a", {"a": 1.0, "b": 0.0}, 1.0, False)]
+
+        calibrated = apply_calibration(examples, predictions, temperature=20.0, abstention_threshold=0.0)
+
+        self.assertEqual(calibrated[0].probabilities, {"a": 1.0, "b": 0.0})
+
+    def test_invalid_probability_vectors_fail_closed(self) -> None:
+        examples = [_example("x", "a", True)]
+        for probabilities in ({"a": 0.5, "b": 0.2}, {"a": math.nan, "b": 1.0}, {"a": -0.5, "b": 1.5}):
+            with self.subTest(probabilities=probabilities), self.assertRaises(ValueError):
+                apply_calibration(
+                    examples,
+                    [Prediction("x", "a", probabilities, 0.5, False)],
+                    temperature=1.0,
+                    abstention_threshold=0.0,
+                )
+
+    def test_calibration_recomputes_argmax_and_never_covers_without_choice(self) -> None:
+        examples = [_example("was_abstained", "a", True), _example("stale_choice", "a", True)]
+        predictions = [
+            Prediction("was_abstained", None, {"a": 0.6, "b": 0.4}, 0.42, True),
+            Prediction("stale_choice", "b", {"a": 0.6, "b": 0.4}, 0.6, False),
+        ]
+
+        calibrated = apply_calibration(examples, predictions, temperature=1.0, abstention_threshold=0.2)
+
+        self.assertEqual([(item.choice, item.abstained) for item in calibrated], [("a", False), ("a", False)])
+
+    def test_answerability_gate_is_preserved_and_labels_do_not_gate(self) -> None:
+        examples = [_example("low_answerability", "a", True), _example("unanswerable", None, False)]
+        predictions = [
+            Prediction("low_answerability", "a", {"a": 0.6, "b": 0.4}, 0.2, False),
+            Prediction("unanswerable", "a", {"a": 0.6, "b": 0.4}, 0.6, False),
+        ]
+
+        default = apply_calibration(examples, predictions, temperature=1.0, abstention_threshold=0.0)
+        relaxed = apply_calibration(
+            examples,
+            predictions,
+            temperature=1.0,
+            abstention_threshold=0.0,
+            answerability_threshold=0.3,
+        )
+
+        self.assertEqual((default[0].choice, default[0].abstained), (None, True))
+        self.assertEqual((default[1].choice, default[1].abstained), ("a", False))
+        self.assertEqual((relaxed[0].choice, relaxed[0].abstained), ("a", False))
+
+    def test_failed_and_absent_distributions_remain_abstained(self) -> None:
+        examples = [_example("failed", "a", True), _example("absent", "a", True)]
+        predictions = [
+            Prediction("failed", None, {}, 0.0, False, error="timeout"),
+            Prediction("absent", "a", {}, 0.9, False),
+        ]
+
+        calibrated = apply_calibration(examples, predictions, temperature=1.0, abstention_threshold=0.0)
+
+        self.assertEqual((calibrated[0].choice, calibrated[0].abstained, calibrated[0].error), (None, True, "timeout"))
+        self.assertEqual((calibrated[1].choice, calibrated[1].abstained, calibrated[1].probabilities), (None, True, {}))
+
+    def test_confidence_above_max_probability_fails_closed(self) -> None:
+        examples = [_example("x", "a", True)]
+        with self.assertRaisesRegex(ValueError, "max_probability"):
+            apply_calibration(
+                examples,
+                [Prediction("x", "a", {"a": 0.5, "b": 0.5}, 0.9, False)],
+                temperature=1.0,
+                abstention_threshold=0.0,
+            )
+
+    def test_threshold_fit_uses_argmax_and_counts_unanswerable_as_errors(self) -> None:
+        examples = [_example("correct", "a", True), _example("stale_choice", "a", True), _example("unknown", None, False)]
+        predictions = [
+            Prediction("correct", "a", {"a": 0.9, "b": 0.1}, 0.9, False),
+            Prediction("stale_choice", "b", {"a": 0.6, "b": 0.4}, 0.58, False),
+            Prediction("unknown", "a", {"a": 0.55, "b": 0.45}, 0.5, False),
+        ]
+
+        details = fit_abstention_threshold_details(examples, predictions, target_risk=0.0)
+        calibrated = apply_calibration(examples, predictions, temperature=1.0, abstention_threshold=details.threshold)
+
+        self.assertAlmostEqual(details.threshold, 0.58)
+        self.assertEqual((details.rows, details.covered_rows, details.risk, details.abstain_all), (3, 2, 0.0, False))
+        self.assertEqual(fit_abstention_threshold(examples, predictions, target_risk=0.0), details.threshold)
+        self.assertEqual([item.abstained for item in calibrated], [False, False, True])
+
+    def test_all_abstain_sentinel_covers_nothing_even_at_confidence_one(self) -> None:
+        examples = [_example("wrong", "a", True)]
+        predictions = [Prediction("wrong", "b", {"a": 0.0, "b": 1.0}, 1.0, False)]
+
+        threshold = fit_abstention_threshold(examples, predictions, target_risk=0.0)
+        at_one = apply_calibration(examples, predictions, temperature=1.0, abstention_threshold=1.0)[0]
+        sentinel = apply_calibration(examples, predictions, temperature=1.0, abstention_threshold=threshold)[0]
+
+        self.assertEqual(threshold, ABSTAIN_ALL_THRESHOLD)
+        self.assertFalse(at_one.abstained)
+        self.assertEqual((sentinel.choice, sentinel.abstained), (None, True))
+        for invalid in (1.5, -0.1, math.nan):
+            with self.subTest(threshold=invalid), self.assertRaisesRegex(ValueError, "abstention_threshold"):
+                apply_calibration(examples, predictions, temperature=1.0, abstention_threshold=invalid)
+
+    def test_unknown_or_duplicate_prediction_ids_fail_closed(self) -> None:
+        examples = [_example("a", "a", True)]
+        with self.assertRaisesRegex(ValueError, "unknown example id"):
+            apply_calibration(
+                examples,
+                [Prediction("ghost", "a", {"a": 1.0}, 1.0, False)],
+                temperature=1.0,
+                abstention_threshold=0.0,
+            )
+        with self.assertRaisesRegex(ValueError, "duplicate prediction"):
+            fit_abstention_threshold(examples, [Prediction("a", "a", {"a": 1.0}, 1.0, False)] * 2)
+
+    def test_calibrate_report_records_provenance_and_rejects_identity_mismatch(self) -> None:
+        config = {
+            "model_id": "vons-test",
+            "backend": "direct",
+            "seed": 7,
+            "encoder": {"name": "encoder", "revision": "r1"},
+            "answerability_threshold": 0.8,
+        }
+        calibration_rows = [_example("c1", "a", True), _example("c2", "b", True), _example("c3", None, False)]
+        calibration_predictions = [
+            Prediction("c1", "a", {"a": 0.9, "b": 0.1}, 0.9, False),
+            Prediction("c2", "b", {"a": 0.3, "b": 0.7}, 0.63, False),
+            Prediction("c3", None, {"a": 0.6, "b": 0.4}, 0.3, True),
+        ]
+        test_rows = [_example("t1", "a", True, "test"), _example("t2", "b", True, "test"), _example("t3", None, False, "test")]
+        test_predictions = [
+            Prediction("t1", "a", {"a": 0.8, "b": 0.2}, 0.8, False),
+            Prediction("t2", "b", {"a": 0.4, "b": 0.6}, 0.42, False),
+            Prediction("t3", None, {}, 0.0, False, error="timeout"),
+        ]
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            calibration_input, calibration_report = root / "calibration.jsonl", root / "calibration.json"
+            test_input, test_report, output = root / "test.jsonl", root / "test.json", root / "calibrated.json"
+            write_jsonl(calibration_input, calibration_rows)
+            write_jsonl(test_input, test_rows)
+            write_report(calibration_report, config=config, summary=summarize(calibration_rows, calibration_predictions), predictions=calibration_predictions)
+            write_report(test_report, config=config, summary=summarize(test_rows, test_predictions), predictions=test_predictions)
+            arguments = {
+                "calibration_input": calibration_input,
+                "calibration_report": calibration_report,
+                "test_input": test_input,
+                "test_report": test_report,
+            }
+
+            calibrate_report(**arguments, output=output, target_risk=0.0)
+            payload = json.loads(output.read_text(encoding="utf-8"), parse_constant=_reject_constant)
+
+            fit = payload["calibration"]
+            self.assertEqual(fit["version"], CALIBRATION_VERSION)
+            self.assertEqual(fit["answerability_threshold"], 0.8)
+            self.assertEqual((fit["temperature_fit_rows"], fit["threshold_fit_rows"], fit["rows"]), (2, 3, 3))
+            self.assertTrue(fit["temperature_at_lower_bound"])
+            self.assertLessEqual(fit["nll_after"], fit["nll_before"])
+            self.assertEqual(payload["inputs"]["test_report"]["sha256"], hashlib.sha256(test_report.read_bytes()).hexdigest())
+            self.assertEqual(payload["model_identity"]["model_id"], "vons-test")
+            self.assertTrue(any("checkpoint_sha256 unavailable" in item for item in payload["limitations"]))
+            self.assertEqual(payload["summary"]["metric_version"], METRIC_VERSION)
+            decisions = {item["example_id"]: (item["choice"], item["abstained"]) for item in payload["predictions"]}
+            self.assertEqual(decisions, {"t1": ("a", False), "t2": (None, True), "t3": (None, True)})
+
+            mismatched = root / "mismatched.json"
+            write_report(mismatched, config={**config, "model_id": "other"}, summary={}, predictions=test_predictions)
+            with self.assertRaisesRegex(ValueError, "model_id"):
+                calibrate_report(**{**arguments, "test_report": mismatched}, output=root / "rejected.json")
+            with self.assertRaisesRegex(ValueError, "overwrite"):
+                calibrate_report(**arguments, output=test_report)
+            self.assertFalse((root / "rejected.json").exists())
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_contract.py

@@ -0,0 +1,40 @@
+import unittest
+
+from vons.contract import (
+    Backend,
+    DecisionRequest,
+    Question,
+    QuestionType,
+    derive_kasi_action,
+    validate_request,
+)
+from vons.kasi import KASIAdapter, KASIProposal
+
+
+class ContractTests(unittest.TestCase):
+    def test_valid_request(self) -> None:
+        validate_request(DecisionRequest("A weather tool is available.", (Question("next", QuestionType.CHOICE, "Choose.", ("call", "clarify")),), Backend.DIRECT, 7))
+
+    def test_duplicate_questions_rejected(self) -> None:
+        request = DecisionRequest("state", (Question("q", QuestionType.CHOICE, "pick", ("a", "b")), Question("q", QuestionType.CHOICE, "pick", ("a", "b"))))
+        with self.assertRaises(ValueError):
+            validate_request(request)
+
+    def test_kasi_confirm_is_wrapper_derived(self) -> None:
+        self.assertEqual(derive_kasi_action(proposed_calls=({"name": "unlock"},), confidence=0.99, risk="high", confirmed_tools=set(), tool_policy={"unlock": "high"}).value, "confirm")
+        self.assertEqual(derive_kasi_action(proposed_calls=({"name": "read"},), confidence=0.99, risk="low", confirmed_tools=set(), tool_policy={"read": "low"}).value, "call")
+
+    def test_unregistered_tool_cannot_call(self) -> None:
+        action = derive_kasi_action(proposed_calls=({"name": "read"},), confidence=0.99, risk="low", tool_policy={})
+        self.assertEqual(action.value, "refuse")
+
+    def test_kasi_response_and_low_confidence(self) -> None:
+        adapter = KASIAdapter(tool_policy={"read_weather": "low"})
+        response = adapter.decide(KASIProposal(response="The answer is ready.", confidence=0.9))
+        self.assertEqual(response.action.value, "respond")
+        clarify = adapter.decide(KASIProposal(calls=(), confidence=0.2))
+        self.assertEqual(clarify.action.value, "clarify")
+
+
+if __name__ == "__main__":
+    unittest.main()