Add TypeSafe SDK serving with verified low/high vLLM routes

README.md

@@ -215,6 +215,45 @@ Keep `enable_thinking=False` for these short decision outputs. The original exam
 
 This example returns standard chat-completion text through `choices[0].message.content`. It demonstrates **full-depth text serving**, not the specialized candidate-probability `/decide` gateway or `effort` routing. It does not enforce the three candidate labels; application-specific decision serving requires the corresponding prompt/compiler and output constraints. The server binds to localhost by default. Blackwell JIT compilation requires a compatible CUDA toolchain; the launcher disables the FlashInfer sampler as in the tested engine configuration.
 
+### TypeSafe SDK API with real low/high vLLM backends
+
+The additional [TypeSafe deployment package](deployment/README.md) exposes `POST /v1/systemone` and `GET /v1/models` for the official `typesafe-sdk==0.7.0`. It routes `high` to the original merged **9B-5949 / 32-layer** model and `low` to a verified **16-layer** export of the same trained checkpoint. The original `serve_vllm.py` remains a standard, full-depth OpenAI text endpoint.
+
+Follow [deployment/README.md](deployment/README.md) to download a pinned HF snapshot, export the trained low-depth model, and launch the two engines and gateway. The gateway checks actual model paths and layer configurations at startup; accepting an effort field alone is not treated as proof of shallow execution.
+
+```python
+import os
+from typesafe_sdk import Choice, RetryPolicy, TypeSafeClient
+
+with TypeSafeClient(
+    base_url="http://127.0.0.1:30013",  # API root; do not append /v1
+    api_key=os.environ["JEV_API_KEY"],  # Your local gateway key
+    model="APUS-OpenJev-v1-9B",
+    retry=RetryPolicy(max_retries=0),
+    timeout=60,
+) as client:
+    result = client.system_one(
+        state="I was charged twice for my order. Please refund the duplicate charge.",
+        questions={"route": Choice(
+            instructions="Select the team that should handle this request.",
+            criteria={
+                "billing": "Payments, refunds, and billing issues",
+                "technical_support": "Technical problems and product errors",
+                "sales": "Pricing inquiries and purchase assistance",
+            },
+        )},
+        extra_body={"effort": "low"},  # Use high for 32 layers; default is high
+    )
+    print(result.choices["route"].choice)
+    print(result.raw_http_response.headers["x-openjev-executed-layers"])
+```
+
+For the **official hosted TypeSafe service**, use `base_url="https://api.typesafe.ai"`, `api_key=os.environ["TYPESAFE_API_KEY"]`, and an official model such as `model="jev-1.13.0"`. Omit `extra_body={"effort": ...}`: this depth control is an APUS extension. The SDK context manager keeps connections reusable across calls. Never reuse a hosted API credential as a local gateway secret.
+
+Compatibility covers synchronous/asynchronous SDK calls, typed Choice/Noul/Score responses, model listing, and documented error handling within the model's [supported limits](deployment/README.md#contract-and-limits). This does not claim identical model behavior or official probability calibration. Multi-question calls are currently evaluated separately. Two-engine depth routing uses additional memory and does not share KV state or automatically continue a shallow request into deeper layers.
+
+See [deployment validation](deployment/VALIDATION.md) for measured results and limitations. The deployment directory retains its source project's [Apache 2.0 license](deployment/LICENSE); this does not change the model weights' licenses.
+
 ## 6. Reproducing the Evaluation
 
 Use the fixed dataset revision `7a63c3d6df2bdc6c8e82dfc566800dc318f0c36b`, preserve question and candidate order, and record the model revision, runtime, dtype, and compute budget. Keep reference labels out of the model input. Report decision accuracy separately from latency, and state precisely where timing starts and ends.

deployment/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

deployment/README.md

@@ -0,0 +1,233 @@
+# APUS TypeSafe SDK gateway with explicit vLLM low/high routing
+
+This directory adds the **official `typesafe-sdk==0.7.0` request/response protocol** to APUS-OpenJev. The local service is an APUS model, not the hosted Jev service. Its probabilities, calibration, quality, and billing do not inherit the hosted service's guarantees.
+
+Two separately loaded vLLM engines serve the same trained checkpoint at different layer depths:
+
+| Effort | Engine | Execution |
+| --- | --- | --- |
+| `high` (default) | Original merged `9B-5949` | 32 layers |
+| `low` | Verified prefix export of that same checkpoint | 16 layers, original final norm and LM head |
+
+This is **explicit request routing between two engines**. It is not automatic confidence-based early exit, shared weights between processes, hidden-state continuation, KV broadcast, or candidate-only LM-head execution. Both vLLM engines compute the full output head; the gateway extracts the requested candidate scores. A client-requested `low` never silently falls back to `high`.
+
+## 1. Install and download the model
+
+Use Linux, Python 3.12, CUDA-capable hardware, and vLLM 0.29.0. The 9B deployment work targets one RTX PRO 6000 Blackwell 96 GB; other hardware needs its own memory and numerical checks. Do not run the reference native runtime's Transformers 5.16.1 requirements in this vLLM environment.
+
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
+pip install vllm==0.29.0 transformers==5.17.0 huggingface-hub==1.32.0 ninja==1.13.2
+pip install fastapi==0.128.8 uvicorn==0.40.0 httpx==0.28.1 httpx2==2.13.0 typesafe-sdk==0.7.0
+```
+
+On Blackwell, configure the compatible CUDA 13 compiler in the same environment:
+
+```bash
+pip install nvidia-cuda-nvcc==13.4.92 nvidia-cuda-crt==13.4.92 nvidia-cuda-cccl==13.3.4.3.1
+export CUDA_HOME="$(python -c 'import sysconfig; print(sysconfig.get_path("purelib") + "/nvidia/cu13")')"
+export PATH="$CUDA_HOME/bin:$PATH"
+"$CUDA_HOME/bin/nvcc" --version
+```
+
+The launch script disables the FlashInfer sampler to match the tested configuration. After downloading this directory, `pip install -r requirements.txt` installs the pinned deployment dependencies. `requirements-test.txt` supports the CPU gateway tests without installing a GPU runtime.
+
+Resolve the repository revision once, then download by that immutable revision. The repository is a family bundle: use the **model subdirectory**, not its root.
+
+```bash
+export APUS_REVISION="$(python -c 'from huggingface_hub import HfApi; print(HfApi().model_info("apus-ailab/APUS-OpenJev-v1").sha)')"
+hf download apus-ailab/APUS-OpenJev-v1 --revision "$APUS_REVISION" \
+  --include '9B-5949/*' 'deployment/*' --local-dir ./APUS-OpenJev-v1
+cd ./APUS-OpenJev-v1/deployment
+export APUS_FULL_MODEL="$(cd ../9B-5949 && pwd)"
+```
+
+If you already downloaded the deployment code separately, the included model-only helper performs the same immutable-revision resolution and prints the resulting model path:
+
+```bash
+python download_model.py --local-dir ../models --revision "$APUS_REVISION"
+# With this layout, set APUS_FULL_MODEL to ../models/9B-5949.
+```
+
+Create a **new separate directory** for the trained 16-layer prefix. The exporter refuses an existing destination and verifies retained tensors; it never modifies the original weights.
+
+```bash
+export APUS_LOW_MODEL="$(dirname "$APUS_FULL_MODEL")/9B-5949-low16"
+python export_low.py --source "$APUS_FULL_MODEL" --output "$APUS_LOW_MODEL"
+```
+
+Start the full engine in terminal A, using an otherwise available GPU:
+
+```bash
+export JEV_VLLM_PYTHON="$VIRTUAL_ENV/bin/python"
+CUDA_VISIBLE_DEVICES=0 JEV_EFFORT=high \
+  JEV_MODEL_PATH="$APUS_FULL_MODEL" JEV_ENGINE_PORT=30002 \
+  JEV_GPU_MEMORY_UTILIZATION=0.70 JEV_MAX_NUM_SEQS=8 \
+  bash run_backend.sh
+```
+
+In terminal B, activate the same environment, set the same `CUDA_HOME` and `APUS_LOW_MODEL` paths, and start the shallow engine:
+
+```bash
+export JEV_VLLM_PYTHON="$VIRTUAL_ENV/bin/python"
+CUDA_VISIBLE_DEVICES=0 JEV_EFFORT=low \
+  JEV_MODEL_PATH="$APUS_LOW_MODEL" JEV_ENGINE_PORT=30004 \
+  JEV_GPU_MEMORY_UTILIZATION=0.22 JEV_MAX_NUM_SEQS=8 \
+  bash run_backend.sh
+```
+
+These defaults allocate separate engine budgets of 70% and 22% of the same 96 GB GPU. They are not appropriate if another workload already occupies that GPU. Compilation can take several minutes. The launcher verifies metadata and weight hashes before starting; this adds sequential disk reads. In terminal C, check both engines:
+
+```bash
+curl -f http://127.0.0.1:30002/health
+curl -f http://127.0.0.1:30004/health
+```
+
+Do not proceed until both are ready. Each foreground process can be stopped with Ctrl-C in its own terminal. Never reuse a port or GPU allocation belonging to another workload. The two engines must belong to the same source checkpoint; archive the export provenance and source revision together. The package uses `max_num_seqs=8` per engine; historical high-only measurements with 32 sequences are a different serving configuration and must not be copied as this setup's result.
+
+## 2. Start the SDK gateway
+
+```bash
+export JEV_MODEL_PATH="$APUS_FULL_MODEL"
+export JEV_HIGH_MODEL_PATH="$APUS_FULL_MODEL"
+export JEV_LOW_MODEL_PATH="$APUS_LOW_MODEL"
+export JEV_HIGH_URL=http://127.0.0.1:30002
+export JEV_LOW_URL=http://127.0.0.1:30004
+export JEV_HIGH_MODEL=apus-openjev-9b-high32
+export JEV_LOW_MODEL=apus-openjev-9b-low16
+export JEV_MODEL_NAME=APUS-OpenJev-v1-9B
+# Supply your own local gateway secret; this is NOT your hosted TypeSafe API key.
+export JEV_API_KEY='replace-with-your-local-gateway-secret'
+python gateway.py --host 127.0.0.1 --port 30013
+```
+
+Startup requires both model directories on the same filesystem as the gateway. It checks 32/16-layer configs, merged indexes, completed low-export provenance, source/export metadata hashes, and each `/v1/models` alias/root against its configured artifact directory. Mismatches fail startup. The tokenizer must come from the full model directory. Engine URLs and aliases must be distinct. Depth headers report the selected verified backend configuration, not per-request layer-hook telemetry; live numerical evaluation remains necessary.
+
+The gateway binds to localhost by default. Configure an authenticated HTTPS proxy before exposing it publicly. Backend URLs are operator configuration, never accepted from incoming requests. Both backend connections and the SDK client can reuse HTTP connections.
+
+## 3. Use the official SDK against APUS
+
+Use the **API root** as `base_url` — do not append `/v1`. The SDK appends `/v1/systemone` and `/v1/models` itself.
+
+```python
+import os
+from typesafe_sdk import Choice, Noul, RetryPolicy, TypeSafeClient
+
+with TypeSafeClient(
+    base_url="http://127.0.0.1:30013",
+    api_key=os.environ["JEV_API_KEY"],
+    model="APUS-OpenJev-v1-9B",
+    retry=RetryPolicy(max_retries=0),
+) as client:
+    print(client.models.list())
+    result = client.system_one(
+        state={
+            "message": "My parcel arrived damaged yesterday. Can I get a refund?",
+            "policy": "Damaged items reported within 30 days qualify for a refund.",
+        },
+        questions={
+            "queue": Choice(
+                instructions="Choose the appropriate customer-support queue.",
+                criteria={"returns": "Returns and refunds", "billing": "Payments and invoices"},
+            ),
+            "eligible": Noul(instructions="Is the customer eligible under this refund policy?"),
+        },
+        extra_body={"effort": "low"},
+    )
+    print(result.answers["queue"].choice)
+    print(result.answers["eligible"].noul)
+    print(result.raw_http_response.headers["x-openjev-executed-layers"])
+```
+
+Use `extra_body={"effort": "high"}` for the full model, or omit it because high is the default. **`effort` is an APUS extension**, not a promise that the hosted TypeSafe API accepts the same field.
+
+Run the complete English customer-support example (Choice + Noul + ordinal Score):
+
+```bash
+python sdk_example.py --effort high
+python sdk_example.py --effort low
+```
+
+Async uses the same fields:
+
+```python
+import asyncio
+import os
+from typesafe_sdk import AsyncTypeSafeClient, Noul, RetryPolicy
+
+async def main():
+    async with AsyncTypeSafeClient(
+        base_url="http://127.0.0.1:30013",
+        api_key=os.environ["JEV_API_KEY"],
+        model="APUS-OpenJev-v1-9B",
+        retry=RetryPolicy(max_retries=0),
+    ) as client:
+        result = await client.system_one(
+            state="The customer received a damaged item yesterday.",
+            questions={"damaged": Noul(instructions="Did the customer report a damaged item?")},
+            extra_body={"effort": "high"},
+        )
+        print(result.answers["damaged"].noul)
+
+asyncio.run(main())
+```
+
+## 4. Use the official hosted TypeSafe service separately
+
+This snippet sends a real request to the hosted service and can incur charges. Keep its credentials separate from the local gateway secret. It deliberately does not send the APUS `effort` extension.
+
+```python
+import os
+from typesafe_sdk import Choice, RetryPolicy, TypeSafeClient
+
+with TypeSafeClient(
+    base_url="https://api.typesafe.ai",
+    api_key=os.environ["TYPESAFE_API_KEY"],
+    model="jev-latest",
+    retry=RetryPolicy(max_retries=0),
+) as client:
+    result = client.system_one(
+        state="The customer was charged twice for the same order.",
+        questions={"queue": Choice(
+            instructions="Choose the appropriate customer-support queue.",
+            criteria={"billing": "Payments and invoices", "shipping": "Delivery and tracking"},
+        )},
+    )
+    print(result.answers["queue"].choice)
+```
+
+## Contract and limits
+
+- Supported SDK 0.7.0 methods: synchronous/asynchronous `system_one` and `models.list`. This SDK version exposes no `models.retrieve` method.
+- `GET /v1/models` lists the APUS model and `jev-latest` as an explicitly labeled **local compatibility alias**. Responses name the actual APUS model.
+- `POST /v1/systemone` accepts `state`, `questions`, `model`, and the optional APUS `effort` extension only. Unknown fields, invalid effort, unsupported models, malformed or duplicate-key JSON fail explicitly.
+- State: string / object / array. Instructions: string / object / array / null. Choice descriptions also allow null; null uses the candidate name. JSON is serialized deterministically; ordinary string descriptions remain unchanged.
+- Choice: 2–16 candidates. Noul: yes/no; optional true/false descriptions affect the question's meaning. Canonical true/false descriptions retain the original binary prompt. Custom descriptions are included explicitly.
+- Score: 1–10 ordered levels, selected by their descriptions; returns the expected zero-based index, probabilities, and the original legend. This differs from the trained binary `score_level` task and has **not established ordinal-score quality or calibration**. A single-level Score has only one possible result: score 0, probability 1, no GPU request, zero model tokens, and executed-layers header 0. Its confidence 1 denotes a degenerate distribution, not evidence that the rubric is objectively correct.
+- At most 16 questions, 1 MiB request body, and 8,191 compiled prompt tokens per question (one output token reserved). Inputs are never silently truncated. Maximum 32 in-flight requests, with a 120-second request deadline.
+- Each question is compiled and scored separately. Usage sums the processed prompt tokens and one scoring token per question; `billing_units` means local decision count, not official monetary billing.
+- Confidence is normalized distribution concentration. Candidate probabilities are uncalibrated conditional softmax; neither quantity inherits official calibration semantics.
+- Response shape uses `model`, `answers`, `usage`; Choice has `choice/confidence/probabilities`, Noul has `noul`, Score has `score/confidence/probabilities/legend`.
+- Headers `x-openjev-effort`, `x-openjev-executed-layers`, and `x-openjev-engine-model` record the chosen route. `x-typesafe-request-id` is a local request identifier.
+
+## Verification status
+
+CPU integration tests use the **real official SDK 0.7.0**, both sync and async, through an ASGI gateway with a deterministic mocked inference backend. They verify protocol, routing, payload validation, and numerical response assembly; they are not GPU quality or performance measurements.
+
+```bash
+pip install -r requirements-test.txt
+python -m pytest -q tests/test_typesafe_gateway.py
+```
+
+Before reporting GPU performance, record immutable model/export identities, prove 16/32-layer engine admission, run the same frozen requests through both routes, retain raw responses and collection timestamps, and compare against a reference using **the same compiled prompts**. In particular, a historic `score_level` record mapped to TypeSafe Noul changes its prompt primitive; do not silently compare it as byte-identical input.
+
+Run a real service smoke test and preserve its raw requests, responses, UTC timestamps, and per-call latency:
+
+```bash
+python smoke_sdk.py --base-url http://127.0.0.1:30013 --output ./sdk-smoke-new-run
+```
+
+This sends five HTTP calls: models, high multi-question, low multi-question, an expected 422 for invalid effort, and an async low request. The two multi-question requests include all three primitives. Use a new output directory for every run. No authentication headers are saved.
+
+Deployment code retains the included Apache 2.0 license and source notices. Model weights retain their applicable upstream licenses.

deployment/VALIDATION.md

@@ -0,0 +1,48 @@
+# Deployment validation — 2026-09-21
+
+The official TypeSafe Python SDK **0.7.0** successfully called this gateway on a real GPU deployment. `high` reached a 32-layer vLLM engine; `low` reached a separately exported 16-layer engine. This is explicit depth selection, not automatic confidence routing.
+
+## Live SDK HTTP results
+
+RTX PRO 6000 Blackwell 96 GB, vLLM 0.29.0, BF16, merged `9B-5949`, one GPU with two resident engines. Local loopback HTTP, one persistent SDK client, concurrency 1, retries disabled. Each effort ran the same frozen80 panel three times. Collection: **2026-09-21 13:46:20–13:46:52 UTC**. Timing covers SDK invocation through complete response validation; it is not streaming TTFT.
+
+| SDK route | Successful | Accuracy per round | Mean | P50 | P95 | P99 |
+| --- | ---: | --- | ---: | ---: | ---: | ---: |
+| high / 32 layers | 240/240 | 67/80 in all three | 70.11 ms | 23.75 ms | 243.10 ms | 290.51 ms |
+| low / 16 layers | 240/240 | 67/80 in all three | 49.17 ms | 22.01 ms | 154.61 ms | 177.58 ms |
+
+Percentiles pool all 240 calls per route; they are not averages of per-round percentiles. Each run scored Browser 12/16, HelpSteer3 13/16, BoolQ 16/16, MNLI 12/16, and Score-derived Noul 14/16. There are only 80 distinct questions from 79 parent groups. These development questions have informed the project; neither significance nor general noninferiority follows from this result.
+
+Mean latency fell **29.86%** (about **1.43×** speed) in this sequential local workload. Median improvement was much smaller. This does not establish a doubling of throughput or a public-network speedup. Serving budgets: high `gpu_memory_utilization=0.70`, `max_num_seqs=32`; low `0.22`, `max_num_seqs=8`; both max length 8192, prefix cache disabled. The supplied launcher defaults to 8 sequences for each route; its concurrent throughput must be benchmarked separately. Resident GPU memory was approximately 90,580 MiB with both engines loaded.
+
+The SDK smoke separately passed model listing, multi-question Choice/Noul/Score at both efforts, invalid-effort error handling, and an asynchronous low request: **5/5 checks**. Full request/response bodies, UTC timestamps, route headers, and raw evaluation records were retained internally; no hosted API credentials are needed for this service.
+
+## Numerical verification and limits
+
+The exporter retained **548 tensors**, preserving their bytes, including the original embedding, final norm and LM head, while removing decoder layers 16–31. The source weights and metadata were checked against their release manifest. A native reference run used layer hooks to confirm that only layers 0–15 ran for all 80 questions.
+
+A separate raw vLLM candidate-scoring comparison used the **same original compiled prompts**:
+
+| Route | Correct | Same selected candidate as native reference | Maximum probability difference |
+| --- | ---: | ---: | ---: |
+| high32 | 67/80 | 80/80 | 0.06422 |
+| low16 | 67/80 | 78/80 | 0.08855 |
+
+Low changed two Browser decisions: one incorrect answer became correct and one correct answer became incorrect. Equal aggregate accuracy does **not** establish identical decisions or numerical parity. Original probability thresholds must be recalibrated for the deployed runtime. The first raw low request took about 1,552 ms before warm execution; SDK measurements above followed raw verification and smoke requests.
+
+The wire benchmark uses the same state, instructions, candidate descriptions and frozen IDs as the official API requests, with the APUS model and effort extension. Historic binary `score_level` records map to TypeSafe **Noul**, changing the internal prompt primitive; the raw-reference comparison and SDK-wire comparison therefore answer different questions. Ordinal Score protocol smoke is not a scored quality benchmark for ordinal rubrics.
+
+## Reproducibility
+
+- Source HF family: `apus-ailab/APUS-OpenJev-v1`, model subdirectory `9B-5949/`; inspected source repository revision `c8a31769918d34e4142b9338b231a7bef59de3f3`. Serving-code publication does not change weights.
+- Frozen panel SHA256: `d6dd45a9c8cb9f5b50254ac5f8f550e0ab1341e993c8657eb89232f64686ebf6`.
+- Protocol tests: **12 passing**, real official SDK sync/async against a real ASGI gateway and mocked scoring engines.
+- Export tests: **9 passing**, standalone CPU tiny-Qwen prefix/readout equivalence, retained tensor identity, source modification and weight-tampering rejection.
+- Live collector tests: **2 passing**; independent offline verification checks all 480 saved requests, IDs, gold scoring, route headers and recorded timing.
+- Serving bundle passes Ruff lint/format and shell syntax checks. A clean OS dependency installation was not tested; GPU tests used the existing verified Runpod environment.
+
+The official hosted service was measured separately over a WAN: the earlier 240 pooled responses had P50/P95/P99 **280.80/376.56/830.45 ms**. A subsequent SDK single-connection 160-call test averaged **301.63 ms**. Those include geography/network effects and must not be divided by these loopback numbers to claim a model speedup.
+
+## Compatibility boundaries
+
+The gateway supports the SDK's synchronous/asynchronous `system_one` and `models.list` methods, typed responses, local bearer auth and documented errors. See README for candidate, context and request limits. This release does not assert unlimited compatibility with every request accepted by the hosted service, official calibration, automatic early exit, shared KV broadcast, or production Browser task completion.

deployment/contracts.py

@@ -0,0 +1,301 @@
+"""Wire validation and deterministic semantic bridge to existing decision prompts."""
+
+import json
+import math
+from dataclasses import dataclass
+
+PROMPT_VERSION = "jev.dynamic.prompt.v2"
+LABELS = tuple("ABCDEFGHIJKLMNOP")
+BINARY_CRITERIA = [
+    {"id": "yes", "description": "The stated proposition is true."},
+    {"id": "no", "description": "The stated proposition is false."},
+]
+
+
+def validate_request(record):
+    for key in ("id", "group_id", "state", "instructions"):
+        if not isinstance(record.get(key), str) or not record[key].strip():
+            raise ValueError(f"{key} must be a nonempty string")
+    if record.get("primitive") not in ("choice", "noul", "score_level"):
+        raise ValueError("unsupported primitive")
+    criteria = record.get("criteria")
+    if not isinstance(criteria, list) or not 2 <= len(criteria) <= len(LABELS):
+        raise ValueError("criteria must contain 2..16 candidates")
+    ids = []
+    for candidate in criteria:
+        if not isinstance(candidate, dict):
+            raise TypeError("candidate must be an object")
+        for key in ("id", "description"):
+            if not isinstance(candidate.get(key), str) or not candidate[key].strip():
+                raise ValueError(f"candidate {key} must be nonempty")
+        ids.append(candidate["id"])
+    if len(set(ids)) != len(ids):
+        raise ValueError("duplicate candidate ids")
+    if record["primitive"] != "choice" and criteria != BINARY_CRITERIA:
+        raise ValueError("noul and score_level require canonical yes/no criteria")
+
+
+def validate_record(record):
+    validate_request(record)
+    if record.get("gold") not in [c["id"] for c in record["criteria"]]:
+        raise ValueError("gold must be a candidate id")
+    if not isinstance(record.get("provenance"), dict):
+        raise TypeError("provenance must be an object")
+
+
+def label_mapping(record):
+    validate_request(record)
+    return dict(zip(LABELS, (c["id"] for c in record["criteria"])))
+
+
+def render_prompt_parts(record):
+    """Text prefix/suffix; callers MUST check tokenizer boundary equivalence."""
+    validate_request(record)
+    prefix = "Shared state:\n" + record["state"] + "\n\n"
+    task = {
+        "primitive": record["primitive"],
+        "instructions": record["instructions"],
+        "criteria": [
+            {"label": label, "description": candidate["description"]}
+            for label, candidate in zip(LABELS, record["criteria"])
+        ],
+    }
+    suffix = json.dumps(task, ensure_ascii=False, sort_keys=True)
+    suffix += (
+        "\nReturn only the selected letter: "
+        + ", ".join(LABELS[: len(record["criteria"])])
+        + ".\nAnswer:"
+    )
+    return prefix, suffix
+
+
+def render_prompt(record):
+    return "".join(render_prompt_parts(record))
+
+
+COMPILER_VERSION = "jev.typesafe.compiler.v1"
+CONFIDENCE_POLICY = "normalized-entropy.v1"
+
+
+class ServingError(Exception):
+    def __init__(self, status, code, message):
+        super().__init__(message)
+        self.status, self.code, self.message = status, code, message
+
+
+def invalid(message):
+    raise ServingError(422, "invalid_request", message)
+
+
+def text(value):
+    if isinstance(value, str) and value.strip():
+        return value
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, allow_nan=False)
+
+
+def content(value):
+    return isinstance(value, (str, dict, list))
+
+
+@dataclass(frozen=True)
+class Question:
+    key: str
+    kind: str
+    record: dict
+    legend: dict | None = None
+
+
+def prepare_request(body, *, model_name, max_questions=16, allow_score=True):
+    if not isinstance(body, dict) or set(body) - {
+        "state",
+        "questions",
+        "model",
+        "effort",
+    }:
+        invalid("Expected state, questions, model and optional effort only")
+    if not isinstance(body.get("model", "jev-latest"), str) or body.get(
+        "model", "jev-latest"
+    ) not in {model_name, "jev-latest"}:
+        raise ServingError(404, "unknown_model", "Model is not served")
+    if not content(body.get("state")):
+        invalid("state must be a string, object or array")
+    questions = body.get("questions")
+    if not isinstance(questions, dict) or not 1 <= len(questions) <= max_questions:
+        invalid("questions must be a nonempty map within the configured limit")
+    result = []
+    for key, question in questions.items():
+        if not isinstance(key, str) or not key.strip():
+            invalid("Question IDs must be nonempty strings")
+        if not isinstance(question, dict) or set(question) - {
+            "type",
+            "instructions",
+            "criteria",
+        }:
+            invalid("Invalid question fields")
+        kind = question.get("type")
+        instruction = question.get("instructions")
+        if instruction is not None and not content(instruction):
+            invalid("instructions must be text, object, array or null")
+        instruction = (
+            text(instruction)
+            if instruction is not None
+            else "Evaluate the state against the supplied criteria."
+        )
+        criteria = question.get("criteria")
+        legend = None
+        internal_kind = kind
+        if kind == "choice":
+            if not isinstance(criteria, dict) or not 2 <= len(criteria) <= len(LABELS):
+                invalid(
+                    "This model supports 2..16 Choice candidates; none are truncated"
+                )
+            candidates = []
+            for name, description in criteria.items():
+                if not isinstance(name, str) or not name.strip():
+                    invalid("Choice names must be nonempty strings")
+                if description is not None and not content(description):
+                    invalid("Invalid Choice description")
+                candidates.append(
+                    {
+                        "id": name,
+                        "description": name
+                        if description is None
+                        else text(description),
+                    }
+                )
+        elif kind == "noul":
+            if criteria is not None:
+                if not isinstance(criteria, dict) or set(criteria) - {"true", "false"}:
+                    invalid("Noul criteria accepts true and false descriptions")
+                if any(v is not None and not content(v) for v in criteria.values()):
+                    invalid("Invalid Noul criterion")
+                if any(v is not None for v in criteria.values()) and criteria != {
+                    "true": BINARY_CRITERIA[0]["description"],
+                    "false": BINARY_CRITERIA[1]["description"],
+                }:
+                    instruction = text(
+                        {"question": instruction, "meaning_of_answers": criteria}
+                    )
+            candidates = [dict(c) for c in BINARY_CRITERIA]
+        elif kind == "score":
+            if not allow_score:
+                raise ServingError(
+                    422,
+                    "unsupported_score",
+                    "Ordinal Score is experimental and disabled; it is not score_level",
+                )
+            if not isinstance(criteria, list) or not 1 <= len(criteria) <= 10:
+                invalid("Score requires 1..10 ordered levels")
+            if any(not content(v) for v in criteria):
+                invalid("Invalid Score level")
+            legend = {str(i): v for i, v in enumerate(criteria)}
+            candidates = [{"id": k, "description": text(v)} for k, v in legend.items()]
+            internal_kind = "choice"
+            instruction = text(
+                {
+                    "question": instruction,
+                    "task": "Select the best matching ordered rubric level. Levels run from lowest to highest.",
+                }
+            )
+        else:
+            invalid("Unsupported question type")
+        record = {
+            "id": key,
+            "group_id": "serving",
+            "state": text(body["state"]),
+            "primitive": internal_kind,
+            "instructions": instruction,
+            "criteria": candidates,
+        }
+        result.append(Question(key, kind, record, legend))
+    return result
+
+
+@dataclass(frozen=True)
+class Compiled:
+    question: Question
+    prompt_ids: list[int]
+    candidate_token_ids: list[int]
+
+
+def compile_question(question, tokenizer, max_tokens=8192):
+    if question.kind == "score" and len(question.record["criteria"]) == 1:
+        return Compiled(question, [], [])
+    prompt = tokenizer.apply_chat_template(
+        [{"role": "user", "content": render_prompt(question.record)}],
+        tokenize=False,
+        add_generation_prompt=True,
+        enable_thinking=False,
+    )
+    ids = tokenizer.encode(prompt, add_special_tokens=False)
+    if not ids or len(ids) > max_tokens:
+        invalid("Compiled prompt exceeds token budget; no truncation is allowed")
+    special = set(tokenizer.all_special_ids)
+    if special.intersection(
+        tokenizer.encode(render_prompt(question.record), add_special_tokens=False)
+    ):
+        invalid("Input contains reserved model control tokens")
+    tokens = []
+    for label in LABELS[: len(question.record["criteria"])]:
+        encoded = tokenizer.encode(label, add_special_tokens=False)
+        if (
+            len(encoded) != 1
+            or tokenizer.encode(prompt + label, add_special_tokens=False)
+            != ids + encoded
+        ):
+            invalid("Candidate is not one token at the answer boundary")
+        if encoded[0] in special or encoded[0] in tokens:
+            invalid("Invalid candidate token mapping")
+        tokens.append(encoded[0])
+    return Compiled(question, ids, tokens)
+
+
+def probabilities(scores):
+    if len(scores) < 2 or any(
+        type(v) not in (int, float) or not math.isfinite(v) for v in scores
+    ):
+        raise ServingError(
+            502, "invalid_distribution", "Backend returned invalid candidate scores"
+        )
+    shift = max(scores)
+    values = [math.exp(v - shift) for v in scores]
+    total = sum(values)
+    return [v / total for v in values]
+
+
+def confidence(probs):
+    if len(probs) == 1:
+        return 1.0
+    entropy = -sum(p * math.log(p) for p in probs if p > 0)
+    return min(1.0, max(0.0, 1.0 - entropy / math.log(len(probs))))
+
+
+def answer(question, probs):
+    keys = [c["id"] for c in question.record["criteria"]]
+    if (
+        len(keys) != len(probs)
+        or any(
+            type(p) not in (int, float) or not math.isfinite(p) or not 0 <= p <= 1
+            for p in probs
+        )
+        or not math.isclose(sum(probs), 1, abs_tol=1e-6)
+    ):
+        raise ServingError(
+            502,
+            "invalid_distribution",
+            "Backend distribution does not match candidates",
+        )
+    if question.kind == "noul":
+        return {"type": "noul", "noul": probs[keys.index("yes")]}
+    value = {
+        "type": question.kind,
+        "probabilities": dict(zip(keys, probs)),
+        "confidence": confidence(probs),
+    }
+    if question.kind == "choice":
+        value["choice"] = keys[max(range(len(probs)), key=probs.__getitem__)]
+    else:
+        value.update(
+            score=sum(i * p for i, p in enumerate(probs)), legend=question.legend
+        )
+    return value

deployment/download_model.py

@@ -0,0 +1,47 @@
+"""Download only the merged 9B-5949 model from one immutable HF snapshot."""
+
+import argparse
+import json
+from pathlib import Path
+import re
+
+
+def main():
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--repo", default="apus-ailab/APUS-OpenJev-v1")
+    p.add_argument("--revision", default="main")
+    p.add_argument("--local-dir", type=Path, required=True)
+    args = p.parse_args()
+    from huggingface_hub import HfApi, snapshot_download
+
+    revision = HfApi().model_info(args.repo, revision=args.revision).sha
+    if not re.fullmatch("[a-f0-9]{40}", revision):
+        raise ValueError("Hub did not return an immutable commit")
+    root = Path(
+        snapshot_download(
+            repo_id=args.repo,
+            revision=revision,
+            allow_patterns=["9B-5949/*"],
+            local_dir=args.local_dir,
+        )
+    )
+    model = root / "9B-5949"
+    config = json.loads((model / "config.json").read_text())
+    if (
+        config["text_config"]["num_hidden_layers"] != 32
+        or (model / "adapter_config.json").exists()
+    ):
+        raise ValueError("Expected the complete merged 32-layer model")
+    print(
+        json.dumps(
+            {
+                "repo": args.repo,
+                "revision": revision,
+                "model_path": str(model.resolve()),
+            }
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()

deployment/export_low.py

@@ -0,0 +1,354 @@
+"""Export actual 16-layer Qwen3.5-9B prefix, preserving its shared norm/head."""
+
+import argparse
+import copy
+from datetime import datetime, timezone
+import hashlib
+import json
+from pathlib import Path
+import re
+import shutil
+
+LAYER = re.compile(r"^model\.language_model\.layers\.(\d+)\.")
+READOUT = {
+    "model.language_model.embed_tokens.weight",
+    "model.language_model.norm.weight",
+    "lm_head.weight",
+}
+
+
+def file_sha(path):
+    h = hashlib.sha256()
+    with Path(path).open("rb") as f:
+        for block in iter(lambda: f.read(8 * 1024 * 1024), b""):
+            h.update(block)
+    return h.hexdigest()
+
+
+def source_snapshot(source):
+    """Stat all root model files; ignore unrelated nested evaluation directories."""
+    return {
+        p.name: {
+            "bytes": p.stat().st_size,
+            "mtime_ns": p.stat().st_mtime_ns,
+            "inode": p.stat().st_ino,
+        }
+        for p in sorted(Path(source).iterdir())
+        if p.is_file()
+    }
+
+
+def assert_source_unchanged(source, before):
+    if source_snapshot(source) != before:
+        raise ValueError(
+            "source model files changed during export; refusing verified publication"
+        )
+
+
+def verify_artifact(path, depth):
+    """Default launcher gate: rehash every weight, not only config and index."""
+    path = Path(path)
+    config = json.loads((path / "config.json").read_text())
+    text = config.get("text_config", {})
+    if (
+        config.get("model_type") != "qwen3_5"
+        or text.get("hidden_size") != 4096
+        or text.get("vocab_size") != 248320
+        or text.get("num_hidden_layers") != depth
+        or len(text.get("layer_types", [])) != depth
+        or (path / "adapter_config.json").exists()
+    ):
+        raise ValueError("backend architecture/depth mismatch")
+    if depth == 32:
+        check_source(path)
+        return
+    if depth != 16 or (path / "EXPORT_INCOMPLETE").exists():
+        raise ValueError("only complete 16/32 exports accepted")
+    manifest = json.loads((path / "export-low-provenance.json").read_text())
+    if (
+        manifest.get("status") != "verified"
+        or manifest.get("actual_depth") != 16
+        or manifest.get("all_retained_tensors_bit_identical") is not True
+    ):
+        raise ValueError("low export provenance is not verified")
+    for name, field in (
+        ("config.json", "export_config_sha256"),
+        ("model.safetensors.index.json", "export_index_sha256"),
+    ):
+        if file_sha(path / name) != manifest[field]:
+            raise ValueError("low config/index SHA mismatch")
+    weights = json.loads((path / "model.safetensors.index.json").read_text())[
+        "weight_map"
+    ]
+    select_keys(weights, 16, 16)
+    entries = manifest["export_weight_files"]
+    expected = {entry["file"]: entry for entry in entries}
+    if len(expected) != len(entries) or set(expected) != set(weights.values()):
+        raise ValueError("low weight manifest/index mismatch")
+    for name, entry in expected.items():
+        if Path(name).name != name or not name.endswith(".safetensors"):
+            raise ValueError("invalid low shard path")
+        if (path / name).stat().st_size != entry["bytes"] or file_sha(
+            path / name
+        ) != entry["sha256"]:
+            raise ValueError(f"low weight SHA mismatch: {name}")
+
+
+def tensor_sha(tensor):
+    import torch
+
+    raw = memoryview(tensor.contiguous().view(torch.uint8).numpy()).cast("B")
+    h = hashlib.sha256()
+    for start in range(0, len(raw), 8 * 1024 * 1024):
+        h.update(raw[start : start + 8 * 1024 * 1024])
+    return h.hexdigest()
+
+
+def prefix_config(config, depth=16):
+    result = copy.deepcopy(config)
+    text = result["text_config"]
+    if (
+        not 0 < depth < text["num_hidden_layers"]
+        or len(text["layer_types"]) != text["num_hidden_layers"]
+    ):
+        raise ValueError("invalid depth or layer_types")
+    text["num_hidden_layers"] = depth
+    text["layer_types"] = text["layer_types"][:depth]
+    if "mlp_only_layers" in text:
+        text["mlp_only_layers"] = [i for i in text["mlp_only_layers"] if i < depth]
+    return result
+
+
+def select_keys(keys, depth, full_depth):
+    kept, removed, seen = [], [], set()
+    for key in sorted(keys):
+        match = LAYER.match(key)
+        if match:
+            i = int(match.group(1))
+            if not 0 <= i < full_depth:
+                raise ValueError("layer outside full depth")
+            seen.add(i)
+            (kept if i < depth else removed).append(key)
+        elif key in READOUT or key.startswith("model.visual."):
+            kept.append(key)
+        else:
+            raise ValueError(f"unexpected weight namespace: {key}")
+    if seen != set(range(full_depth)) or not READOUT <= set(kept):
+        raise ValueError("missing decoder, embedding, final norm or lm_head")
+    return kept, removed
+
+
+def check_source(source):
+    config = json.loads((source / "config.json").read_text())
+    text = config.get("text_config", {})
+    if (
+        config.get("model_type") != "qwen3_5"
+        or config.get("architectures") != ["Qwen3_5ForConditionalGeneration"]
+        or text.get("num_hidden_layers") != 32
+        or text.get("hidden_size") != 4096
+        or text.get("vocab_size") != 248320
+        or text.get("intermediate_size") != 12288
+        or config.get("tie_word_embeddings") is not False
+        or text.get("tie_word_embeddings") is not False
+        or (source / "adapter_config.json").exists()
+    ):
+        raise ValueError("only merged, untied dense Qwen3.5-9B full32 accepted")
+    depth = json.loads((source / "depth_config.json").read_text())
+    if depth.get("exit_depth") != 16 or depth.get("full_depth") != 32:
+        raise ValueError("source must declare trained exits 16/32")
+    if text.get("layer_types") != (["linear_attention"] * 3 + ["full_attention"]) * 8:
+        raise ValueError("unexpected Qwen3.5-9B hybrid schedule")
+    weight_map = json.loads((source / "model.safetensors.index.json").read_text())[
+        "weight_map"
+    ]
+    kept, removed = select_keys(weight_map, 16, 32)
+    manifest = json.loads((source / "release-manifest.json").read_text())
+    expected = {r["path"]: r["sha256"] for r in manifest["files"]}
+    source_files = []
+    for name in sorted(set(weight_map.values())):
+        if Path(name).name != name or not name.endswith(".safetensors"):
+            raise ValueError("weight shard must be a simple safetensors filename")
+        observed = file_sha(source / name)
+        if expected.get(name) != observed:
+            raise ValueError(f"source weight SHA mismatch: {name}")
+        source_files.append(
+            {"file": name, "sha256": observed, "bytes": (source / name).stat().st_size}
+        )
+    for name in (
+        "config.json",
+        "depth_config.json",
+        "model.safetensors.index.json",
+        "tokenizer.json",
+        "tokenizer_config.json",
+        "chat_template.jinja",
+    ):
+        if name not in expected or file_sha(source / name) != expected[name]:
+            raise ValueError(f"source metadata SHA mismatch: {name}")
+    return config, weight_map, kept, removed, source_files
+
+
+def copy_weights(source, output, weight_map, kept):
+    from safetensors import safe_open
+    from safetensors.torch import save_file
+
+    shards = [
+        n
+        for n in sorted(set(weight_map.values()))
+        if any(weight_map[k] == n for k in kept)
+    ]
+    output_map, files, manifests = {}, [], []
+    total = 0
+    for ordinal, name in enumerate(shards, 1):
+        selected = sorted(k for k in kept if weight_map[k] == name)
+        with safe_open(source / name, framework="pt", device="cpu") as src:
+            if set(src.keys()) != {k for k, v in weight_map.items() if v == name}:
+                raise ValueError("source shard/index mismatch")
+            tensors = {k: src.get_tensor(k) for k in selected}
+            total += sum(t.numel() * t.element_size() for t in tensors.values())
+            out_name = f"model-low16-{ordinal:05d}-of-{len(shards):05d}.safetensors"
+            save_file(tensors, output / out_name, metadata={"format": "pt"})
+            with safe_open(output / out_name, framework="pt", device="cpu") as dst:
+                if set(dst.keys()) != set(selected):
+                    raise ValueError("exported keys mismatch")
+                for key in selected:
+                    original, exported = tensors[key], dst.get_tensor(key)
+                    checksum = tensor_sha(original)
+                    if (
+                        original.dtype != exported.dtype
+                        or original.shape != exported.shape
+                        or checksum != tensor_sha(exported)
+                    ):
+                        raise ValueError(f"exported tensor changed: {key}")
+                    manifests.append(
+                        {
+                            "name": key,
+                            "shape": list(original.shape),
+                            "dtype": str(original.dtype),
+                            "sha256": checksum,
+                        }
+                    )
+                    output_map[key] = out_name
+            files.append(
+                {
+                    "file": out_name,
+                    "sha256": file_sha(output / out_name),
+                    "bytes": (output / out_name).stat().st_size,
+                }
+            )
+        print(
+            json.dumps(
+                {"verified_export_shard": out_name, "tensor_count": len(selected)}
+            ),
+            flush=True,
+        )
+    if set(output_map) != set(kept):
+        raise ValueError("export index incomplete")
+    (output / "model.safetensors.index.json").write_text(
+        json.dumps(
+            {"metadata": {"total_size": total}, "weight_map": output_map}, indent=2
+        )
+        + "\n"
+    )
+    return files, manifests
+
+
+def export(source, output):
+    from safetensors import safe_open
+
+    source, output = Path(source).resolve(), Path(output).resolve()
+    if output.exists() or source in output.parents:
+        raise ValueError("output must be a new directory outside source model")
+    before = source_snapshot(source)
+    config, weight_map, kept, removed, source_files = check_source(source)
+    for name in sorted(set(weight_map.values())):
+        with safe_open(source / name, framework="pt", device="cpu") as handle:
+            if set(handle.keys()) != {k for k, v in weight_map.items() if v == name}:
+                raise ValueError("source index/shard mismatch")
+            for key, shape in {
+                "lm_head.weight": (248320, 4096),
+                "model.language_model.embed_tokens.weight": (248320, 4096),
+                "model.language_model.norm.weight": (4096,),
+            }.items():
+                if (
+                    weight_map[key] == name
+                    and tuple(handle.get_slice(key).get_shape()) != shape
+                ):
+                    raise ValueError(f"unexpected shared readout shape: {key}")
+    output.mkdir(parents=True, exist_ok=False)
+    (output / "EXPORT_INCOMPLETE").write_text(
+        "Only provenance status=verified denotes success.\n"
+    )
+    (output / "config.json").write_text(
+        json.dumps(prefix_config(config), indent=2) + "\n"
+    )
+    for name in (
+        "tokenizer.json",
+        "tokenizer_config.json",
+        "chat_template.jinja",
+        "generation_config.json",
+        "special_tokens_map.json",
+        "added_tokens.json",
+        "vocab.json",
+        "merges.txt",
+        "preprocessor_config.json",
+        "processor_config.json",
+        "video_preprocessor_config.json",
+        "LICENSE",
+    ):
+        if (source / name).is_file():
+            shutil.copy2(source / name, output / name)
+    files, tensors = copy_weights(source, output, weight_map, kept)
+    provenance = {
+        "format": "openjev.vllm-low-prefix.v1",
+        "status": "verified",
+        "created_utc": datetime.now(timezone.utc).isoformat(),
+        "source": str(source),
+        "source_full_depth": 32,
+        "actual_depth": 16,
+        "dynamic_continuation": False,
+        "selection": "original decoder 0..15 + shared embed/final norm/lm_head + all visual tensors",
+        "source_config_sha256": file_sha(source / "config.json"),
+        "source_depth_config": json.loads((source / "depth_config.json").read_text()),
+        "source_release_manifest_sha256": file_sha(source / "release-manifest.json"),
+        "source_index_sha256": file_sha(source / "model.safetensors.index.json"),
+        "source_weight_files": source_files,
+        "export_config_sha256": file_sha(output / "config.json"),
+        "export_index_sha256": file_sha(output / "model.safetensors.index.json"),
+        "export_weight_files": files,
+        "retained_tensors": tensors,
+        "removed_tensors": removed,
+        "all_retained_tensors_bit_identical": True,
+        "vllm_numerical_parity": "not established by CPU export; requires independent GPU comparison",
+        "script_sha256": file_sha(__file__),
+    }
+    assert_source_unchanged(source, before)
+    provenance["source_files_stat_before_after"] = before
+    provenance["source_files_unchanged_during_export"] = True
+    (output / "export-low-provenance.json").write_text(
+        json.dumps(provenance, indent=2) + "\n"
+    )
+    (output / "EXPORT_INCOMPLETE").unlink()
+    return provenance
+
+
+def main():
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--source", type=Path, required=True)
+    p.add_argument("--output", type=Path, required=True)
+    args = p.parse_args()
+    result = export(args.source, args.output)
+    print(
+        json.dumps(
+            {
+                "status": result["status"],
+                "output": str(args.output),
+                "actual_depth": 16,
+                "retained_tensors": len(result["retained_tensors"]),
+            }
+        ),
+        flush=True,
+    )
+
+
+if __name__ == "__main__":
+    main()

deployment/gateway.py

@@ -0,0 +1,430 @@
+"""TypeSafe SDK wire gateway to distinct shallow/full vLLM scoring engines."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+import hashlib
+import hmac
+import json
+import math
+import os
+from pathlib import Path
+import re
+import uuid
+
+import httpx
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from contracts import (
+    ServingError,
+    answer,
+    compile_question,
+    prepare_request,
+    probabilities,
+)
+
+
+def canonical_root(value):
+    url = httpx.URL(value)
+    path = url.path.rstrip("/").removesuffix("/v1").rstrip("/")
+    return str(url.copy_with(path=path))
+
+
+@dataclass(frozen=True)
+class Settings:
+    high_url: str
+    low_url: str
+    high_model: str
+    low_model: str
+    api_key: str
+    model_name: str = "APUS-OpenJev-v1-9B"
+    max_body_bytes: int = 1_048_576
+    max_questions: int = 16
+    max_tokens: int = 8191
+    max_inflight: int = 32
+    timeout: float = 120.0
+    high_model_path: str | None = None
+    low_model_path: str | None = None
+
+    def __post_init__(self):
+        for value in (self.high_url, self.low_url):
+            url = httpx.URL(value)
+            if (
+                url.scheme not in ("http", "https")
+                or not url.host
+                or url.username
+                or url.password
+                or url.query
+                or url.fragment
+            ):
+                raise ValueError(
+                    "Backend URLs must be HTTP(S) without credentials/query"
+                )
+        if canonical_root(self.high_url) == canonical_root(self.low_url):
+            raise ValueError(
+                "Low and high must use distinct engine URLs; no silent full-depth fallback"
+            )
+        if not all((self.high_model, self.low_model, self.api_key, self.model_name)):
+            raise ValueError(
+                "Both model aliases and a nonempty local API key are required"
+            )
+        if self.high_model == self.low_model:
+            raise ValueError("Low and high engine model aliases must be distinct")
+
+    @classmethod
+    def from_env(cls):
+        return cls(
+            high_url=os.environ["JEV_HIGH_URL"],
+            low_url=os.environ["JEV_LOW_URL"],
+            high_model=os.environ["JEV_HIGH_MODEL"],
+            low_model=os.environ["JEV_LOW_MODEL"],
+            api_key=os.environ["JEV_API_KEY"],
+            high_model_path=os.environ["JEV_HIGH_MODEL_PATH"],
+            low_model_path=os.environ["JEV_LOW_MODEL_PATH"],
+            model_name=os.environ.get("JEV_MODEL_NAME", "APUS-OpenJev-v1-9B"),
+        )
+
+
+def unique_object(pairs):
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("Duplicate JSON keys")
+        result[key] = value
+    return result
+
+
+def reject_constant(value):
+    raise ValueError("Nonfinite JSON values are forbidden")
+
+
+def parse_scores(data, tokens):
+    try:
+        choices = data["choices"]
+        if len(choices) != 1 or len(choices[0]["logprobs"]["top_logprobs"]) != 1:
+            raise ValueError
+        values = choices[0]["logprobs"]["top_logprobs"][0]
+        if not isinstance(values, dict):
+            raise ValueError
+        by_id = {}
+        for key, value in values.items():
+            if (
+                not re.fullmatch(r"token_id:(0|[1-9]\d*)", key)
+                or type(value) not in (float, int)
+                or not math.isfinite(value)
+                or value > 0
+            ):
+                raise ValueError
+            by_id[int(key.split(":")[1])] = value
+        return [by_id[token] for token in tokens]
+    except (KeyError, TypeError, ValueError, IndexError):
+        raise ServingError(
+            502,
+            "invalid_backend_scores",
+            "Backend omitted valid candidate token logprobs",
+        ) from None
+
+
+def endpoint(url, path):
+    root = url.rstrip("/")
+    return root + (path.removeprefix("/v1") if root.endswith("/v1") else path)
+
+
+def file_sha(path):
+    return hashlib.sha256(Path(path).read_bytes()).hexdigest()
+
+
+def verify_artifacts(settings):
+    """Bind configured backend roots to real model configs and export identity."""
+    if not settings.high_model_path or not settings.low_model_path:
+        raise ValueError("Both JEV_HIGH_MODEL_PATH and JEV_LOW_MODEL_PATH are required")
+    roots = {
+        "high": Path(settings.high_model_path).resolve(),
+        "low": Path(settings.low_model_path).resolve(),
+    }
+    for effort, depth in (("high", 32), ("low", 16)):
+        root = roots[effort]
+        cfg = json.loads((root / "config.json").read_text())
+        text = cfg.get("text_config", cfg)
+        if (
+            cfg.get("model_type") not in ("qwen3_5", "qwen3_5_text")
+            or text.get("num_hidden_layers") != depth
+            or len(text.get("layer_types", [])) != depth
+            or text.get("hidden_size") != 4096
+        ):
+            raise ValueError(
+                "Backend artifact does not declare the required execution depth"
+            )
+        if (root / "adapter_config.json").exists() or (
+            root / "EXPORT_INCOMPLETE"
+        ).exists():
+            raise ValueError("Backend artifact is not a completed merged model")
+        if not (root / "model.safetensors.index.json").is_file():
+            raise ValueError("Backend artifact has no merged weight index")
+    low, high = roots["low"], roots["high"]
+    proof = json.loads((low / "export-low-provenance.json").read_text())
+    if (
+        proof.get("status") != "verified"
+        or proof.get("actual_depth") != 16
+        or proof.get("all_retained_tensors_bit_identical") is not True
+    ):
+        raise ValueError("Low artifact has not passed prefix export verification")
+    for key, path in {
+        "export_config_sha256": low / "config.json",
+        "export_index_sha256": low / "model.safetensors.index.json",
+        "source_config_sha256": high / "config.json",
+        "source_index_sha256": high / "model.safetensors.index.json",
+        "source_release_manifest_sha256": high / "release-manifest.json",
+    }.items():
+        if proof.get(key) != file_sha(path):
+            raise ValueError(
+                "Low export provenance does not match the configured source or export metadata"
+            )
+    return roots
+
+
+def create_app(settings, tokenizer, transport=None, check_backends=True):
+    @asynccontextmanager
+    async def lifespan(app):
+        async with httpx.AsyncClient(
+            timeout=settings.timeout,
+            trust_env=False,
+            follow_redirects=False,
+            transport=transport,
+        ) as client:
+            app.state.client = client
+            if check_backends:
+                roots = verify_artifacts(settings)
+                for effort, url, alias in (
+                    ("low", settings.low_url, settings.low_model),
+                    ("high", settings.high_url, settings.high_model),
+                ):
+                    response = await client.get(endpoint(url, "/v1/models"))
+                    response.raise_for_status()
+                    matched = [m for m in response.json()["data"] if m["id"] == alias]
+                    if (
+                        len(matched) != 1
+                        or not matched[0].get("root")
+                        or Path(matched[0]["root"]).resolve() != roots[effort]
+                    ):
+                        raise RuntimeError(
+                            "Engine alias/root does not match the verified depth artifact"
+                        )
+            app.state.ready = True
+            yield
+            app.state.ready = False
+
+    app = FastAPI(lifespan=lifespan)
+    app.state.ready = False
+    app.state.inflight = 0
+
+    def authorize(request):
+        authorization = request.headers.get("authorization", "")
+        if not hmac.compare_digest(
+            authorization.encode(), ("Bearer " + settings.api_key).encode()
+        ):
+            raise ServingError(401, "unauthorized", "Invalid local API key")
+
+    @app.middleware("http")
+    async def request_id_header(request, call_next):
+        response = await call_next(request)
+        response.headers.setdefault("x-typesafe-request-id", str(uuid.uuid4()))
+        return response
+
+    @app.exception_handler(ServingError)
+    async def serving_error(_request, exc):
+        return JSONResponse(
+            status_code=exc.status,
+            content={"error": {"code": exc.code, "message": exc.message}},
+        )
+
+    @app.get("/health")
+    async def health():
+        return JSONResponse(
+            status_code=200 if app.state.ready else 503,
+            content={
+                "ready": app.state.ready,
+                "model": settings.model_name,
+                "efforts": {"low": 16, "high": 32},
+                "routing": "separate-vllm-engines",
+                "automatic_routing": False,
+            },
+        )
+
+    @app.get("/v1/models")
+    async def models(request: Request):
+        authorize(request)
+        return {
+            "models": [
+                {"name": name, "description": description, "release_date": "2026-09-21"}
+                for name, description in [
+                    (
+                        settings.model_name,
+                        "APUS local decision model; explicit low16/high32; uncalibrated candidate scores.",
+                    ),
+                    (
+                        "jev-latest",
+                        "Compatibility alias for "
+                        + settings.model_name
+                        + "; NOT the official Jev model.",
+                    ),
+                ]
+            ]
+        }
+
+    @app.post("/v1/systemone")
+    async def systemone(request: Request):
+        authorize(request)
+        if not app.state.ready:
+            raise ServingError(503, "not_ready", "Backends are not ready")
+        if app.state.inflight >= settings.max_inflight:
+            raise ServingError(429, "busy", "Gateway in-flight budget exceeded")
+        app.state.inflight += 1
+        try:
+            async with asyncio.timeout(settings.timeout):
+                raw = bytearray()
+                async for chunk in request.stream():
+                    raw.extend(chunk)
+                    if len(raw) > settings.max_body_bytes:
+                        raise ServingError(
+                            413, "request_too_large", "Request byte budget exceeded"
+                        )
+                try:
+                    body = json.loads(
+                        raw,
+                        object_pairs_hook=unique_object,
+                        parse_constant=reject_constant,
+                    )
+                    if not isinstance(body, dict):
+                        raise ValueError
+                except (ValueError, TypeError, RecursionError, UnicodeError):
+                    raise ServingError(
+                        422, "invalid_json", "Malformed JSON object"
+                    ) from None
+                effort = body.get("effort", "high")
+                if effort not in ("low", "high"):
+                    raise ServingError(
+                        422, "invalid_effort", "effort must be low or high"
+                    )
+                questions = prepare_request(
+                    body,
+                    model_name=settings.model_name,
+                    max_questions=settings.max_questions,
+                    allow_score=True,
+                )
+                compiled = [
+                    compile_question(q, tokenizer, max_tokens=settings.max_tokens)
+                    for q in questions
+                ]
+                url, model, depth = (
+                    (settings.low_url, settings.low_model, 16)
+                    if effort == "low"
+                    else (settings.high_url, settings.high_model, 32)
+                )
+                answers = {}
+                for item in compiled:
+                    if not item.prompt_ids:
+                        answers[item.question.key] = answer(item.question, [1.0])
+                        continue
+                    payload = {
+                        "model": model,
+                        "prompt": item.prompt_ids,
+                        "max_tokens": 1,
+                        "n": 1,
+                        "stream": False,
+                        "echo": False,
+                        "add_special_tokens": False,
+                        "logprobs": len(item.candidate_token_ids),
+                        "logprob_token_ids": item.candidate_token_ids,
+                        "return_tokens_as_token_ids": True,
+                        "temperature": 1.0,
+                        "top_p": 1.0,
+                        "top_k": -1,
+                        "min_p": 0.0,
+                        "frequency_penalty": 0.0,
+                        "presence_penalty": 0.0,
+                        "repetition_penalty": 1.0,
+                    }
+                    response = await app.state.client.post(
+                        endpoint(url, "/v1/completions"), json=payload
+                    )
+                    if response.status_code != 200:
+                        raise ServingError(
+                            502,
+                            "backend_error",
+                            f"Inference backend returned HTTP {response.status_code}",
+                        )
+                    try:
+                        data = json.loads(
+                            response.content,
+                            object_pairs_hook=unique_object,
+                            parse_constant=reject_constant,
+                        )
+                    except (ValueError, TypeError, UnicodeError, RecursionError):
+                        raise ServingError(
+                            502, "backend_json", "Backend returned invalid JSON"
+                        ) from None
+                    answers[item.question.key] = answer(
+                        item.question,
+                        probabilities(parse_scores(data, item.candidate_token_ids)),
+                    )
+                result = {
+                    "model": settings.model_name,
+                    "answers": answers,
+                    "usage": {
+                        "input_tokens": sum(len(c.prompt_ids) for c in compiled),
+                        "output_tokens": sum(bool(c.prompt_ids) for c in compiled),
+                        "billing_units": len(compiled),
+                    },
+                }
+                return JSONResponse(
+                    result,
+                    headers={
+                        "x-openjev-effort": effort,
+                        "x-openjev-executed-layers": str(
+                            depth if any(c.prompt_ids for c in compiled) else 0
+                        ),
+                        "x-openjev-engine-model": model,
+                        "x-typesafe-request-id": str(uuid.uuid4()),
+                    },
+                )
+        except (TimeoutError, httpx.TimeoutException):
+            raise ServingError(
+                504, "deadline_exceeded", "Inference request exceeded timeout"
+            ) from None
+        except httpx.HTTPError:
+            raise ServingError(
+                502, "backend_transport", "Inference backend connection failed"
+            ) from None
+        finally:
+            app.state.inflight -= 1
+
+    return app
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=30013)
+    args = parser.parse_args()
+    from transformers import AutoTokenizer
+    import uvicorn
+
+    settings = Settings.from_env()
+    if (
+        Path(os.environ["JEV_MODEL_PATH"]).resolve()
+        != Path(settings.high_model_path).resolve()
+    ):
+        raise ValueError("Tokenizer must come from the configured full-depth model")
+    tokenizer = AutoTokenizer.from_pretrained(
+        os.environ["JEV_MODEL_PATH"], local_files_only=True
+    )
+    uvicorn.run(create_app(settings, tokenizer), host=args.host, port=args.port)
+
+
+if __name__ == "__main__":
+    main()

deployment/requirements-test.txt

@@ -0,0 +1,7 @@
+# CPU SDK/gateway tests can run without installing vLLM or PyTorch.
+fastapi==0.128.8
+uvicorn==0.40.0
+httpx==0.28.1
+httpx2==2.13.0
+typesafe-sdk==0.7.0
+pytest==9.0.2

deployment/requirements.txt

@@ -0,0 +1,10 @@
+# vLLM owns the CUDA PyTorch dependency; use a compatible CUDA 13 compiler on Blackwell.
+vllm==0.29.0
+transformers==5.17.0
+huggingface-hub==1.32.0
+ninja==1.13.2
+fastapi==0.128.8
+uvicorn==0.40.0
+httpx==0.28.1
+httpx2==2.13.0
+typesafe-sdk==0.7.0

deployment/run_backend.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Launch one dedicated depth backend; never stops another process.
+set -euo pipefail
+BUNDLE=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+: "${JEV_VLLM_PYTHON:?Absolute Python path in the vLLM 0.29.0 venv}"
+: "${JEV_MODEL_PATH:?Path to full32 merged model or verified exported low16}"
+: "${CUDA_VISIBLE_DEVICES:?Choose exactly one GPU UUID or index}"
+JEV_EFFORT=${JEV_EFFORT:-low}
+case "$JEV_EFFORT" in
+  low) DEPTH=16; DEFAULT_PORT=30004; DEFAULT_ALIAS=apus-openjev-9b-low16; DEFAULT_MEMORY=0.22 ;;
+  high) DEPTH=32; DEFAULT_PORT=30002; DEFAULT_ALIAS=apus-openjev-9b-high32; DEFAULT_MEMORY=0.7 ;;
+  *) echo 'JEV_EFFORT must be high or low' >&2; exit 1 ;;
+esac
+JEV_ENGINE_PORT=${JEV_ENGINE_PORT:-$DEFAULT_PORT}
+JEV_MODEL_ALIAS=${JEV_MODEL_ALIAS:-$DEFAULT_ALIAS}
+JEV_GPU_MEMORY_UTILIZATION=${JEV_GPU_MEMORY_UTILIZATION:-$DEFAULT_MEMORY}
+JEV_MAX_MODEL_LEN=${JEV_MAX_MODEL_LEN:-8192}
+JEV_MAX_NUM_SEQS=${JEV_MAX_NUM_SEQS:-8}
+[[ "$JEV_VLLM_PYTHON" = /* && -x "$JEV_VLLM_PYTHON" ]] || exit 1
+[[ "$CUDA_VISIBLE_DEVICES" =~ ^([0-9]+|GPU-[a-fA-F0-9-]+)$ ]] || exit 1
+export PATH="$(dirname -- "$JEV_VLLM_PYTHON"):$PATH"
+if [[ -n "${CUDA_HOME:-}" ]]; then
+  [[ -x "$CUDA_HOME/bin/nvcc" ]] || { echo 'Invalid CUDA_HOME/bin/nvcc' >&2; exit 1; }
+  export PATH="$CUDA_HOME/bin:$PATH"
+fi
+# This checks the target port and artifact only. Co-residence with high is intentional.
+"$JEV_VLLM_PYTHON" - "$JEV_MODEL_PATH" "$DEPTH" "$JEV_ENGINE_PORT" "$BUNDLE" <<'PY'
+import importlib.metadata,json,socket,sys
+from pathlib import Path
+p=Path(sys.argv[1]); depth=int(sys.argv[2]); port=int(sys.argv[3])
+assert importlib.metadata.version('vllm')=='0.29.0', 'vLLM must be 0.29.0'
+sys.path.insert(0,sys.argv[4])
+from export_low import verify_artifact
+verify_artifact(p,depth)
+with socket.socket() as s:
+    s.bind(('127.0.0.1',port))
+print(json.dumps({'model':str(p),'actual_depth':depth,'port':port,'dynamic_continuation':False}),flush=True)
+PY
+export HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 TOKENIZERS_PARALLELISM=false
+export VLLM_USE_FLASHINFER_SAMPLER=0
+export OMP_NUM_THREADS=${OMP_NUM_THREADS:-8}
+exec "$JEV_VLLM_PYTHON" "$(dirname -- "$JEV_VLLM_PYTHON")/vllm" serve "$JEV_MODEL_PATH" \
+ --served-model-name "$JEV_MODEL_ALIAS" --host 127.0.0.1 --port "$JEV_ENGINE_PORT" \
+ --dtype bfloat16 --tensor-parallel-size 1 --max-model-len "$JEV_MAX_MODEL_LEN" \
+ --language-model-only --gpu-memory-utilization "$JEV_GPU_MEMORY_UTILIZATION" \
+ --max-num-seqs "$JEV_MAX_NUM_SEQS" --max-num-batched-tokens "$JEV_MAX_MODEL_LEN" \
+ --max-logprobs 256 --logprobs-mode raw_logprobs --generation-config vllm \
+ --no-enable-prefix-caching

deployment/sdk_example.py

@@ -0,0 +1,59 @@
+"""English customer-support examples using the official TypeSafe Python SDK."""
+
+import argparse
+import os
+
+from typesafe_sdk import Choice, Noul, RetryPolicy, Score, TypeSafeClient
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--base-url", default="http://127.0.0.1:30013")
+    parser.add_argument("--model", default="APUS-OpenJev-v1-9B")
+    parser.add_argument("--effort", choices=["low", "high"], default="high")
+    args = parser.parse_args()
+    with TypeSafeClient(
+        base_url=args.base_url,
+        api_key=os.environ["JEV_API_KEY"],
+        model=args.model,
+        retry=RetryPolicy(max_retries=0),
+    ) as client:
+        print(client.models.list().model_dump_json(indent=2))
+        result = client.system_one(
+            state={
+                "customer_message": "My order arrived damaged yesterday. I would like a refund.",
+                "policy": "A damaged item reported within 30 days is eligible for a refund.",
+            },
+            questions={
+                "support_queue": Choice(
+                    instructions="Choose the team that should handle this ticket.",
+                    criteria={
+                        "returns": "Damaged items, returns, and refunds",
+                        "billing": "Invoice or payment issues",
+                        "shipping": "Tracking and delivery updates",
+                    },
+                ),
+                "refund_eligible": Noul(
+                    instructions="Does the stated policy make this customer eligible for a refund?"
+                ),
+                "urgency": Score(
+                    instructions="Rate the urgency of this support ticket.",
+                    criteria=[
+                        "Routine question",
+                        "Customer needs timely assistance",
+                        "Immediate safety or security risk",
+                    ],
+                ),
+            },
+            extra_body={"effort": args.effort},
+        )
+        print(result.model_dump_json(indent=2))
+        print("Effort:", result.raw_http_response.headers.get("x-openjev-effort"))
+        print(
+            "Configured execution layers:",
+            result.raw_http_response.headers.get("x-openjev-executed-layers"),
+        )
+
+
+if __name__ == "__main__":
+    main()

deployment/smoke_sdk.py

@@ -0,0 +1,209 @@
+"""Live official-SDK protocol smoke; writes requests/responses, never auth headers."""
+
+import argparse
+import asyncio
+from datetime import datetime, timezone
+import importlib.metadata
+import json
+import os
+from pathlib import Path
+import time
+
+from typesafe_sdk import (
+    AsyncTypeSafeClient,
+    Choice,
+    Noul,
+    RetryPolicy,
+    Score,
+    TypeSafeClient,
+    TypeSafeAPIError,
+)
+
+
+def now():
+    return datetime.now(timezone.utc).isoformat()
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--base-url", default="http://127.0.0.1:30013")
+    parser.add_argument("--model", default="APUS-OpenJev-v1-9B")
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+    args.output.mkdir(parents=True, exist_ok=False)
+    common = {
+        "base_url": args.base_url,
+        "api_key": os.environ["JEV_API_KEY"],
+        "model": args.model,
+        "retry": RetryPolicy(max_retries=0),
+        "timeout": 120,
+    }
+    rows = []
+
+    def record(name, started, timer, response, request):
+        raw = response.raw_http_response
+        row = {
+            "case": name,
+            "started_at": started,
+            "finished_at": now(),
+            "elapsed_ms": (time.perf_counter() - timer) * 1000,
+            "request": json.loads(raw.request.content)
+            if raw.request.content
+            else request,
+            "status_code": raw.status_code,
+            "response_text": raw.text,
+            "response_headers": {
+                k: v
+                for k, v in raw.headers.items()
+                if k.lower()
+                in (
+                    "x-openjev-effort",
+                    "x-openjev-executed-layers",
+                    "x-openjev-engine-model",
+                    "x-typesafe-request-id",
+                    "content-type",
+                )
+            },
+        }
+        rows.append(row)
+        with (args.output / "requests.jsonl").open("a") as out:
+            out.write(json.dumps(row, ensure_ascii=False) + "\n")
+
+    state = {
+        "message": "My order arrived damaged yesterday. I would like a refund.",
+        "policy": "Damaged goods reported within 30 days qualify for a refund.",
+    }
+    questions = {
+        "queue": Choice(
+            instructions="Choose the support team.",
+            criteria={"returns": "Damaged items and refunds", "billing": None},
+        ),
+        "eligible": Noul(
+            instructions="Is this customer eligible under the stated policy?"
+        ),
+        "urgency": Score(
+            instructions="Rate support urgency.",
+            criteria=[
+                "Routine",
+                {"meaning": "Timely attention required"},
+                ["Immediate safety risk"],
+            ],
+        ),
+    }
+    with TypeSafeClient(**common) as sdk:
+        t = time.perf_counter()
+        started = now()
+        result = sdk.models.list()
+        record("models", started, t, result, {"method": "GET", "path": "/v1/models"})
+        assert any(m.name == args.model for m in result.models)
+        for effort, depth in [("high", "32"), ("low", "16")]:
+            t = time.perf_counter()
+            started = now()
+            result = sdk.system_one(
+                state=state, questions=questions, extra_body={"effort": effort}
+            )
+            record(
+                "multi-" + effort,
+                started,
+                t,
+                result,
+                {
+                    "state": state,
+                    "questions": questions,
+                    "model": args.model,
+                    "effort": effort,
+                },
+            )
+            assert (
+                result.raw_http_response.headers["x-openjev-executed-layers"] == depth
+            )
+            assert set(result.answers) == set(questions)
+            assert result.answers["queue"].choice in ("returns", "billing")
+            assert 0 <= result.answers["eligible"].noul <= 1
+            assert result.answers["urgency"].legend[1] == {
+                "meaning": "Timely attention required"
+            }
+            assert (
+                abs(
+                    result.answers["urgency"].score
+                    - sum(
+                        k * v
+                        for k, v in result.answers["urgency"].probabilities.items()
+                    )
+                )
+                < 1e-6
+            )
+        t = time.perf_counter()
+        started = now()
+        try:
+            sdk.system_one(
+                state="Support ticket.",
+                questions={"q": Noul()},
+                extra_body={"effort": "invalid"},
+            )
+        except TypeSafeAPIError as exc:
+            status = exc.status
+            error_body = exc.body
+            row = {
+                "case": "invalid-effort",
+                "started_at": started,
+                "finished_at": now(),
+                "elapsed_ms": (time.perf_counter() - t) * 1000,
+                "request": {
+                    "state": "Support ticket.",
+                    "questions": {"q": {"type": "noul"}},
+                    "effort": "invalid",
+                },
+                "status_code": status,
+                "response_text": json.dumps(error_body),
+            }
+            rows.append(row)
+            with (args.output / "requests.jsonl").open("a") as out:
+                out.write(json.dumps(row) + "\n")
+            assert status == 422
+        else:
+            raise AssertionError("Invalid effort was silently accepted")
+
+    async def run_async():
+        async with AsyncTypeSafeClient(**common) as sdk:
+            t = time.perf_counter()
+            started = now()
+            result = await sdk.system_one(
+                state="The customer requests a refund.",
+                questions={"refund": Noul(instructions="Is this a refund request?")},
+                extra_body={"effort": "low"},
+            )
+            record(
+                "async-low",
+                started,
+                t,
+                result,
+                {
+                    "state": "The customer requests a refund.",
+                    "questions": {
+                        "refund": {
+                            "type": "noul",
+                            "instructions": "Is this a refund request?",
+                        }
+                    },
+                    "effort": "low",
+                },
+            )
+            assert result.raw_http_response.headers["x-openjev-executed-layers"] == "16"
+
+    asyncio.run(run_async())
+    summary = {
+        "status": "passed",
+        "sdk_version": importlib.metadata.version("typesafe-sdk"),
+        "base_url": args.base_url,
+        "model": args.model,
+        "completed_at": now(),
+        "cases": len(rows),
+        "scope": "SDK wire/routing smoke, not model-quality or performance acceptance",
+    }
+    (args.output / "summary.json").write_text(json.dumps(summary, indent=2) + "\n")
+    print(json.dumps(summary))
+
+
+if __name__ == "__main__":
+    main()

deployment/tests/test_typesafe_gateway.py

@@ -0,0 +1,364 @@
+"""Official SDK 0.7.0 through real ASGI gateway, with deterministic backend."""
+
+import asyncio
+import json
+from pathlib import Path
+import sys
+
+import httpx
+import httpx2
+import pytest
+from fastapi.testclient import TestClient
+from typesafe_sdk import (
+    AsyncTypeSafeClient,
+    Choice,
+    Noul,
+    Score,
+    TypeSafeClient,
+    RetryPolicy,
+)
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from gateway import Settings, create_app  # noqa: E402
+from contracts import BINARY_CRITERIA, prepare_request, compile_question  # noqa: E402
+
+
+class Tokenizer:
+    all_special_ids = [0]
+
+    def apply_chat_template(self, messages, **kwargs):
+        assert kwargs["enable_thinking"] is False
+        return "<chat>" + messages[0]["content"] + "</chat>"
+
+    def encode(self, text, **kwargs):
+        return [ord(c) + 1 for c in text]
+
+
+@pytest.fixture
+def service():
+    calls = []
+
+    def upstream(request):
+        payload = json.loads(request.content)
+        calls.append((request.url.host, payload))
+        tokens = payload["logprob_token_ids"]
+        scores = {f"token_id:{t}": -(i + 1.0) for i, t in enumerate(tokens)}
+        return httpx.Response(
+            200, json={"choices": [{"logprobs": {"top_logprobs": [scores]}}]}
+        )
+
+    settings = Settings(
+        "http://high:8000", "http://low:8000", "apus-high32", "apus-low16", "test-key"
+    )
+    with TestClient(
+        create_app(
+            settings,
+            Tokenizer(),
+            transport=httpx.MockTransport(upstream),
+            check_backends=False,
+        )
+    ) as web:
+        yield web, calls
+
+
+def sdk_transport(web):
+    def handler(req):
+        result = web.request(
+            req.method,
+            req.url.raw_path.decode(),
+            content=req.content,
+            headers=dict(req.headers),
+        )
+        return httpx2.Response(
+            result.status_code, content=result.content, headers=dict(result.headers)
+        )
+
+    return httpx2.MockTransport(handler)
+
+
+def client(web, **kwargs):
+    return TypeSafeClient(
+        base_url="http://local",
+        api_key="test-key",
+        retry=RetryPolicy(max_retries=0),
+        transport=sdk_transport(web),
+        **kwargs,
+    )
+
+
+def test_sync_sdk_all_primitives_and_models(service):
+    web, calls = service
+    with client(web) as sdk:
+        listed = sdk.models.list()
+        assert listed.models[0].name == "APUS-OpenJev-v1-9B"
+        assert "NOT the official" in listed.models[1].description
+        response = sdk.system_one(
+            state={"ticket": "My delivery is late."},
+            questions={
+                "queue": Choice(
+                    instructions="Select the support queue.",
+                    criteria={"shipping": "Delivery issues", "billing": None},
+                ),
+                "refund": Noul(
+                    instructions=["Decide eligibility"],
+                    criteria={"true": {"rule": "eligible"}, "false": ["ineligible"]},
+                ),
+                "urgency": Score(
+                    instructions="Rate urgency.",
+                    criteria=[
+                        "Can wait",
+                        {"description": "Time-sensitive"},
+                        ["Immediate"],
+                    ],
+                ),
+            },
+            extra_body={"effort": "low"},
+        )
+    assert response.answers["queue"].choice == "shipping"
+    assert 0 < response.answers["refund"].noul < 1
+    assert response.answers["urgency"].legend[1] == {"description": "Time-sensitive"}
+    assert response.answers["urgency"].score == pytest.approx(
+        sum(k * v for k, v in response.answers["urgency"].probabilities.items())
+    )
+    assert response.raw_http_response.headers["x-openjev-executed-layers"] == "16"
+    assert len(calls) == 3 and all(host == "low" for host, _ in calls)
+    assert all(p["model"] == "apus-low16" and p["max_tokens"] == 1 for _, p in calls)
+
+
+def test_async_sdk_default_high(service):
+    web, calls = service
+
+    async def run():
+        async with AsyncTypeSafeClient(
+            base_url="http://local",
+            api_key="test-key",
+            retry=RetryPolicy(max_retries=0),
+            transport=sdk_transport(web),
+        ) as sdk:
+            assert (await sdk.models.list()).models
+            result = await sdk.system_one(
+                state="Customer needs a refund.",
+                questions={"eligible": Noul(instructions="Is this a refund request?")},
+            )
+            assert result.raw_http_response.headers["x-openjev-effort"] == "high"
+            assert result.raw_http_response.headers["x-openjev-executed-layers"] == "32"
+
+    asyncio.run(run())
+    assert calls[0][0] == "high"
+
+
+def test_auth_and_invalid_sdk_extra_body(service):
+    web, calls = service
+    assert web.get("/v1/models").status_code == 401
+    body = {"state": "ticket", "questions": {"q": {"type": "noul"}}}
+    headers = {"Authorization": "Bearer test-key"}
+    for extra in (
+        {"effort": "medium"},
+        {"unexpected": True},
+        {"model": []},
+        {"effort": {}},
+    ):
+        assert web.post(
+            "/v1/systemone", json={**body, **extra}, headers=headers
+        ).status_code in (404, 422)
+    assert calls == []
+
+
+def test_exact_prompt_plain_choice_and_canonical_noul():
+    criterion = {c["id"]: c["description"] for c in BINARY_CRITERIA}
+    q = prepare_request(
+        {
+            "state": "state",
+            "questions": {
+                "q": {"type": "choice", "instructions": "task", "criteria": criterion}
+            },
+        },
+        model_name="apus",
+    )[0]
+    assert q.record["criteria"] == BINARY_CRITERIA
+    nq = prepare_request(
+        {
+            "state": "state",
+            "questions": {
+                "q": {
+                    "type": "noul",
+                    "instructions": "task",
+                    "criteria": {
+                        "true": BINARY_CRITERIA[0]["description"],
+                        "false": BINARY_CRITERIA[1]["description"],
+                    },
+                }
+            },
+        },
+        model_name="apus",
+    )[0]
+    assert nq.record["instructions"] == "task"
+    assert nq.record["primitive"] == "noul"
+    with pytest.raises(Exception, match="budget"):
+        compile_question(nq, Tokenizer(), max_tokens=5)
+
+
+def test_no_silent_low_same_engine():
+    with pytest.raises(ValueError, match="distinct engine"):
+        Settings("http://same:80", "http://same:80/", "high", "low", "key")
+    with pytest.raises(ValueError, match="aliases"):
+        Settings("http://a", "http://b", "same", "same", "key")
+
+
+def test_missing_backend_candidates_fails():
+    settings = Settings("http://a", "http://b", "high", "low", "key")
+    transport = httpx.MockTransport(
+        lambda req: httpx.Response(
+            200, json={"choices": [{"logprobs": {"top_logprobs": [{}]}}]}
+        )
+    )
+    with TestClient(
+        create_app(settings, Tokenizer(), transport=transport, check_backends=False)
+    ) as web:
+        r = web.post(
+            "/v1/systemone",
+            headers={"Authorization": "Bearer key"},
+            json={"state": "x", "questions": {"q": {"type": "noul"}}},
+        )
+        assert r.status_code == 502
+        assert r.json()["error"]["code"] == "invalid_backend_scores"
+
+
+def test_duplicate_json_and_oversized_fail(service):
+    web, _ = service
+    headers = {"Authorization": "Bearer test-key"}
+    assert (
+        web.post(
+            "/v1/systemone", headers=headers, content='{"state":"a","state":"b"}'
+        ).status_code
+        == 422
+    )
+    assert (
+        web.post("/v1/systemone", headers=headers, content="x" * 1_048_577).status_code
+        == 413
+    )
+
+
+def test_deterministic_singleton_and_unknown_model(service):
+    web, calls = service
+    headers = {"Authorization": "Bearer test-key"}
+    base = {"state": "x", "questions": {"q": {"type": "score", "criteria": ["only"]}}}
+    response = web.post("/v1/systemone", headers=headers, json=base)
+    assert response.status_code == 200
+    assert response.json()["answers"]["q"]["score"] == 0
+    assert response.headers["x-openjev-executed-layers"] == "0"
+    assert calls == []
+    base.update(model="official-other")
+    assert web.post("/v1/systemone", headers=headers, json=base).status_code == 404
+
+
+def artifact_settings(tmp_path):
+    from gateway import file_sha
+
+    high, low = tmp_path / "high", tmp_path / "low"
+    for root, depth in ((high, 32), (low, 16)):
+        root.mkdir()
+        (root / "config.json").write_text(
+            json.dumps(
+                {
+                    "model_type": "qwen3_5",
+                    "text_config": {
+                        "num_hidden_layers": depth,
+                        "hidden_size": 4096,
+                        "layer_types": ["full_attention"] * depth,
+                    },
+                }
+            )
+        )
+        (root / "model.safetensors.index.json").write_text("{}")
+    (high / "release-manifest.json").write_text("{}")
+    proof = {
+        "status": "verified",
+        "actual_depth": 16,
+        "all_retained_tensors_bit_identical": True,
+    }
+    for key, path in {
+        "export_config_sha256": low / "config.json",
+        "export_index_sha256": low / "model.safetensors.index.json",
+        "source_config_sha256": high / "config.json",
+        "source_index_sha256": high / "model.safetensors.index.json",
+        "source_release_manifest_sha256": high / "release-manifest.json",
+    }.items():
+        proof[key] = file_sha(path)
+    (low / "export-low-provenance.json").write_text(json.dumps(proof))
+    return Settings(
+        "http://high",
+        "http://low",
+        "high32",
+        "low16",
+        "key",
+        high_model_path=str(high),
+        low_model_path=str(low),
+    )
+
+
+def test_artifact_depth_and_provenance_fail_closed(tmp_path):
+    from gateway import verify_artifacts
+
+    settings = artifact_settings(tmp_path)
+    assert verify_artifacts(settings)["low"] == tmp_path / "low"
+    cfg = tmp_path / "low" / "config.json"
+    cfg.write_text((tmp_path / "high" / "config.json").read_text())
+    with pytest.raises(ValueError, match="depth"):
+        verify_artifacts(settings)
+
+
+def test_startup_binds_engine_root_to_verified_depth(tmp_path):
+    settings = artifact_settings(tmp_path)
+
+    def upstream(req):
+        # Wrong low root advertises high artifacts despite a distinct low alias.
+        alias = "low16" if req.url.host == "low" else "high32"
+        return httpx.Response(
+            200, json={"data": [{"id": alias, "root": settings.high_model_path}]}
+        )
+
+    with pytest.raises(RuntimeError, match="alias/root"):
+        with TestClient(
+            create_app(settings, Tokenizer(), transport=httpx.MockTransport(upstream))
+        ):
+            pass
+
+
+def test_sdk_rejects_unknown_extension_via_http(service):
+    from typesafe_sdk import TypeSafeUnprocessableEntityError
+
+    web, _ = service
+    with client(web) as sdk, pytest.raises(TypeSafeUnprocessableEntityError):
+        sdk.system_one(
+            state="Customer ticket", questions={"q": Noul()}, extra_body={"unknown": 1}
+        )
+
+
+def test_live_smoke_script_with_real_sdk(service, tmp_path, monkeypatch):
+    import smoke_sdk
+
+    web, _ = service
+    monkeypatch.setenv("JEV_API_KEY", "test-key")
+    monkeypatch.setattr(
+        smoke_sdk,
+        "TypeSafeClient",
+        lambda **kw: TypeSafeClient(transport=sdk_transport(web), **kw),
+    )
+    monkeypatch.setattr(
+        smoke_sdk,
+        "AsyncTypeSafeClient",
+        lambda **kw: AsyncTypeSafeClient(transport=sdk_transport(web), **kw),
+    )
+    output = tmp_path / "smoke"
+    monkeypatch.setattr(sys, "argv", ["smoke_sdk.py", "--output", str(output)])
+    smoke_sdk.main()
+    report = json.loads((output / "summary.json").read_text())
+    assert report["status"] == "passed" and report["cases"] == 5
+    rows = [
+        json.loads(line)
+        for line in (output / "requests.jsonl").read_text().splitlines()
+    ]
+    assert rows[0]["response_headers"]["x-typesafe-request-id"]
+    assert rows[1]["request"]["questions"]["queue"]["type"] == "choice"
+    assert "test-key" not in (output / "requests.jsonl").read_text()

deployment/tests/test_vllm_depth_export.py

@@ -0,0 +1,237 @@
+"""CPU proof: exported half-depth uses original layers, norm, and readout."""
+
+import importlib.util
+import json
+from pathlib import Path
+
+import pytest
+import torch
+from safetensors import safe_open
+from safetensors.torch import save_file
+from transformers import (
+    Qwen3_5Config,
+    Qwen3_5ForConditionalGeneration,
+    Qwen3_5TextConfig,
+)
+
+
+spec = importlib.util.spec_from_file_location(
+    "export_low", Path(__file__).parents[1] / "export_low.py"
+)
+module = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(module)
+
+
+def test_actual_32_to_16_prefix_logits_and_saved_tensors(tmp_path):
+    torch.set_num_threads(1)
+    text = Qwen3_5TextConfig(
+        vocab_size=64,
+        hidden_size=32,
+        intermediate_size=48,
+        num_hidden_layers=32,
+        num_attention_heads=2,
+        num_key_value_heads=1,
+        head_dim=16,
+        linear_key_head_dim=8,
+        linear_value_head_dim=8,
+        linear_num_key_heads=2,
+        linear_num_value_heads=2,
+        layer_types=(["linear_attention"] * 3 + ["full_attention"]) * 8,
+        rope_parameters={
+            "rope_type": "default",
+            "rope_theta": 10000.0,
+            "partial_rotary_factor": 1.0,
+            "mrope_section": [2, 3, 3],
+        },
+    )
+    config = Qwen3_5Config(
+        text_config=text,
+        vision_config={
+            "depth": 1,
+            "hidden_size": 32,
+            "intermediate_size": 48,
+            "num_heads": 2,
+            "out_hidden_size": 32,
+            "num_position_embeddings": 16,
+        },
+    )
+    config._attn_implementation = "eager"
+    config.text_config._attn_implementation = "eager"
+    config.text_config.num_hidden_layers = 32
+    config.text_config.layer_types = (["linear_attention"] * 3 + ["full_attention"]) * 8
+    config.tie_word_embeddings = False
+    config.text_config.tie_word_embeddings = False
+    torch.manual_seed(47)
+    full = Qwen3_5ForConditionalGeneration(config).eval()
+    state = full.state_dict()
+    source, output = tmp_path / "source", tmp_path / "low"
+    source.mkdir()
+    output.mkdir()
+    save_file(state, source / "model.safetensors", metadata={"format": "pt"})
+    weight_map = {k: "model.safetensors" for k in state}
+    kept, removed = module.select_keys(weight_map, 16, 32)
+    assert len(removed) > 0
+    assert module.READOUT <= set(kept)
+    assert all(
+        not module.LAYER.match(k) or int(module.LAYER.match(k).group(1)) < 16
+        for k in kept
+    )
+    files, tensors = module.copy_weights(source, output, weight_map, kept)
+    short_config = module.prefix_config(config.to_dict())
+    assert short_config["vision_config"] == config.to_dict()["vision_config"]
+    assert short_config["text_config"]["num_hidden_layers"] == 16
+    assert len(short_config["text_config"]["layer_types"]) == 16
+    loaded = {}
+    for f in files:
+        with safe_open(output / f["file"], framework="pt") as handle:
+            loaded.update({key: handle.get_tensor(key) for key in handle.keys()})
+    low_config = Qwen3_5Config.from_dict(short_config)
+    low_config._attn_implementation = "eager"
+    low_config.text_config._attn_implementation = "eager"
+    low = Qwen3_5ForConditionalGeneration(low_config).eval()
+    low.load_state_dict(loaded, strict=True)
+    assert len(low.model.language_model.layers) == 16
+    assert len(tensors) == len(loaded)
+    for key in module.READOUT:
+        torch.testing.assert_close(loaded[key], state[key], rtol=0, atol=0)
+    ids, candidates = torch.tensor([[4, 5, 6, 7]]), torch.tensor([10, 11, 12])
+    with torch.no_grad():
+        captured = []
+        hook = full.model.language_model.layers[15].register_forward_hook(
+            lambda _module, _inputs, output: captured.append(output.detach().clone())
+        )
+        try:
+            full(input_ids=ids, use_cache=False)
+        finally:
+            hook.remove()
+        # Independently capture the full model's layer-16 residual, then apply
+        # its original final norm and head. No monorepo runtime dependency.
+        native = full.lm_head(
+            full.model.language_model.norm(captured[0][:, -1])
+        ).index_select(-1, candidates)
+        exported = (
+            low(input_ids=ids, use_cache=False)
+            .logits[:, -1]
+            .index_select(-1, candidates)
+        )
+    torch.testing.assert_close(native, exported, atol=1e-6, rtol=1e-5)
+    assert (
+        json.loads((output / "model.safetensors.index.json").read_text())["metadata"][
+            "total_size"
+        ]
+        > 0
+    )
+
+
+@pytest.mark.parametrize("missing", sorted(module.READOUT))
+def test_readout_cannot_be_dropped(missing):
+    keys = (module.READOUT - {missing}) | {
+        f"model.language_model.layers.{i}.weight" for i in range(32)
+    }
+    with pytest.raises(ValueError, match="missing"):
+        module.select_keys(keys, 16, 32)
+
+
+def test_unknown_adapter_namespace_rejected():
+    keys = (
+        module.READOUT
+        | {f"model.language_model.layers.{i}.weight" for i in range(32)}
+        | {"readout.adapter.weight"}
+    )
+    with pytest.raises(ValueError, match="unexpected"):
+        module.select_keys(keys, 16, 32)
+
+
+def test_existing_output_never_overwritten(tmp_path):
+    with pytest.raises(ValueError, match="new directory"):
+        module.export(tmp_path / "unused", tmp_path)
+
+
+def test_source_stat_change_rejects_verified_publication(tmp_path):
+    path = tmp_path / "weights"
+    path.write_bytes(b"original")
+    snapshot = module.source_snapshot(tmp_path)
+    module.assert_source_unchanged(tmp_path, snapshot)
+    path.write_bytes(b"changed-longer")
+    with pytest.raises(ValueError, match="changed during export"):
+        module.assert_source_unchanged(tmp_path, snapshot)
+
+
+def test_launcher_full_low_weight_hash_detects_tampering(tmp_path):
+    config = {
+        "model_type": "qwen3_5",
+        "text_config": {
+            "hidden_size": 4096,
+            "vocab_size": 248320,
+            "num_hidden_layers": 16,
+            "layer_types": ["linear_attention"] * 16,
+        },
+    }
+    (tmp_path / "config.json").write_text(json.dumps(config))
+    keys = module.READOUT | {
+        f"model.language_model.layers.{i}.weight" for i in range(16)
+    }
+    (tmp_path / "model.safetensors.index.json").write_text(
+        json.dumps({"weight_map": {key: "model.safetensors" for key in keys}})
+    )
+    shard = tmp_path / "model.safetensors"
+    shard.write_bytes(b"original-weights")
+    manifest = {
+        "status": "verified",
+        "actual_depth": 16,
+        "all_retained_tensors_bit_identical": True,
+        "export_config_sha256": module.file_sha(tmp_path / "config.json"),
+        "export_index_sha256": module.file_sha(
+            tmp_path / "model.safetensors.index.json"
+        ),
+        "export_weight_files": [
+            {
+                "file": shard.name,
+                "bytes": shard.stat().st_size,
+                "sha256": module.file_sha(shard),
+            }
+        ],
+    }
+    (tmp_path / "export-low-provenance.json").write_text(json.dumps(manifest))
+    module.verify_artifact(tmp_path, 16)
+    shard.write_bytes(b"tampered-weights")
+    with pytest.raises(ValueError, match="weight SHA mismatch"):
+        module.verify_artifact(tmp_path, 16)
+
+
+def test_launcher_high_release_weight_hash_detects_tampering(tmp_path):
+    config = {
+        "model_type": "qwen3_5",
+        "architectures": ["Qwen3_5ForConditionalGeneration"],
+        "tie_word_embeddings": False,
+        "text_config": {
+            "hidden_size": 4096,
+            "vocab_size": 248320,
+            "intermediate_size": 12288,
+            "num_hidden_layers": 32,
+            "tie_word_embeddings": False,
+            "layer_types": (["linear_attention"] * 3 + ["full_attention"]) * 8,
+        },
+    }
+    (tmp_path / "config.json").write_text(json.dumps(config))
+    (tmp_path / "depth_config.json").write_text(
+        json.dumps({"exit_depth": 16, "full_depth": 32})
+    )
+    for name in ("tokenizer.json", "tokenizer_config.json", "chat_template.jinja"):
+        (tmp_path / name).write_text("mock tokenization asset")
+    keys = module.READOUT | {
+        f"model.language_model.layers.{i}.weight" for i in range(32)
+    }
+    (tmp_path / "model.safetensors.index.json").write_text(
+        json.dumps({"weight_map": {key: "model.safetensors" for key in keys}})
+    )
+    shard = tmp_path / "model.safetensors"
+    shard.write_bytes(b"original-weights")
+    entries = [
+        {"path": p.name, "sha256": module.file_sha(p)} for p in tmp_path.iterdir()
+    ]
+    (tmp_path / "release-manifest.json").write_text(json.dumps({"files": entries}))
+    module.verify_artifact(tmp_path, 32)
+    shard.write_bytes(b"tampered-weights")
+    with pytest.raises(ValueError, match="weight SHA mismatch"):
+        module.verify_artifact(tmp_path, 32)