laya-system-one 1.1.0-alpha.0 → 1.1.0

package/README.md

@@ -1,299 +1,384 @@
-# Laya System-One
-
-**System 1 decision engine** — a multilingual INT8 transformer that answers typed questions (choice / score / yes-no) about any text, in milliseconds, offline.
-
-Wire-compatible with the **TypeSafe Jev** `/v1/systemone` protocol: send state + typed questions, get structured decisions back.
-
-```bash
-npm install laya-system-one
-```
-
-```js
-import { Laya } from 'laya-system-one';
-
-const laya = await Laya.load();          // model is acquired on first use (once)
-const out = await laya.predict(
-  'We were billed twice on the March invoice and want a refund.',
-  {
-    department: {
-      type: 'choice',
-      instructions: 'Which department should handle this?',
-      criteria: { billing: 'refunds and invoices', tech: 'bugs', sales: 'upgrades' }
-    },
-    churn:     { type: 'noul',  instructions: 'Is the user at churn risk?', threshold: 0.5 },
-    severity:  { type: 'score', instructions: 'Urgency?', criteria: ['low', 'mid', 'high'] }
-  }
-);
-
-console.log(out.answers.department.choice); // → "billing"
-```
-
-Or run it as a service:
-
-```bash
-npx laya-system-one --port 8080
-curl -X POST http://localhost:8080/v1/systemone \
-  -H "Content-Type: application/json" \
-  -d '{"state":"I was charged twice and need a refund.","questions":{"dept":{"type":"choice","instructions":"Which department?","criteria":{"billing":"refunds","tech":"bugs"}}}}'
-```
-
----
-
-## What it actually is
-
-A single ONNX checkpoint (`model.onnx`, ~324 MB, INT8) trained to score answer options for three question types, plus a small runtime that:
-
-1. renders the state and the question options into a prompt,
-2. runs one forward pass,
-3. turns the logits into calibrated probabilities.
-
-The runtime is JavaScript (Node/Bun/browser) and executes that forward pass in exactly two ways — pick one with `--backend` or `LAYA_BACKEND`:
-
-| backend | what it is | when to use |
-|---|---|---|
-| `native` **(default)** | the `laya-serve` binary bundled in the package (Rust: Axum + tokenizers + ONNX Runtime, statically linked) | fastest path, zero system dependencies, any OS |
-| `wasm` | pure-Rust `tract` compiled to WASM, bundled in the package | browsers and extreme portability |
-
-There are **no external runtime dependencies**: no `onnxruntime-*`, no `@huggingface/transformers`, nothing to download besides the model. The tokenizer itself is a pure-JS BPE implementation (`src/bpe-tokenizer.js`) verified token-for-token against the reference `tokenizers` crate that the native binary links — so both backends see exactly the same input ids.
-
-> **Note on WebGPU:** earlier versions advertised WebGPU acceleration. Measured reality: ONNX Runtime's Node WebGPU execution provider falls back to CPU per-op with large overhead — it is consistently *slower* than the native backend. WebGPU is not used server-side.
-
----
-
-## How the heavy pieces arrive
-
-The entry package is small on purpose (**~8.5 MB**): source, tokenizer and the
-wasm fallback. The binaries (150+ MB for every platform) and the model
-(324 MB) are published as separate `@sys-one` packages and installed as
-`optionalDependencies`, so npm fetches only what the machine needs:
-
-| package | selected by | size |
-| --- | --- | --- |
-| `@sys-one/laya-serve-<os>-<arch>` | npm's `os`/`cpu` fields | 8–26 MB |
-| `@sys-one/laya-serve-universal` | fallback for exotic platforms | ~76 MB |
-| `@sys-one/laya-model-chunk-00` … `-12` | always (all 13) | ~24 MB each |
-
-A `linux/x64` machine installs `laya-serve-linux-x64` and nothing else;
-a `linux/ppc64` machine matches none of the specific packages and gets the
-universal one. No package installs all of them.
-
-Two things worth knowing about how the selection works, because both were
-verified by experiment rather than assumed:
-
-- **`libc` cannot select.** The field exists but is unreliable (undocumented
-  shorthand, and real packages have shipped bugs where `--libc=glibc` pulls
-  the musl build too). So the glibc and musl builds of a Linux arch travel
-  **together** in one package, and the loader picks at runtime.
-- **Exclusions are AND-ed.** `os: ["!darwin", "!win32"]` means "not both",
-  not "either", so the complement of the specific packages cannot be spelled
-  out. The universal package lists the exotic cpus and OSes explicitly
-  instead: skipped wherever a specific package applies, selected everywhere
-  else.
-
-The model is assembled from its chunk packages on first use and verified
-against `models/model.manifest.json` (sha256 of the model *and* of every
-chunk), written atomically — a killed process cannot leave a corrupt model
-behind, the next run retries. The order is:
-
-1. `LAYA_MODEL_PATH` — explicit path to a `model.onnx` (file or directory);
-2. a `model.onnx` already present in the package's `models/` directory;
-3. `~/.cache/laya-system-one/model.onnx` — previously assembled copy;
-4. the installed `@sys-one/laya-model-chunk-*` packages (the normal path);
-5. the npm registry, if the chunks were not installed as dependencies;
-6. the GitHub Release asset — **opt-in only** (`LAYA_ALLOW_GITHUB_FALLBACK=1`),
-   kept for compatibility with 1.0.0 installs.
-
-### Offline / air-gapped installs
-
-```bash
-LAYA_PREFETCH_MODEL=1 npm install laya-system-one   # fetch during install
-# or point at a model you already have:
-LAYA_MODEL_PATH=/opt/models/model.onnx
-# or drop chunk files somewhere and point at them:
-LAYA_MODEL_CHUNKS_DIR=/opt/models/chunks
-```
-
----
-
-## API
-
-### `Laya.load(options)` → `laya`
-
-| option | default | description |
-|---|---|---|
-| `backend` | `'native'` | `native` \| `wasm` (or env `LAYA_BACKEND`) |
-| `modelDir` | `<package>/models` | where `model.onnx` and `tokenizer.json` live |
-| `apiKey` | `null` | Bearer token required by the HTTP layer |
-| `port` / `host` | `0` / `127.0.0.1` | where the native server binds |
-
-### `laya.predict(state, questions, model?)` → `Promise<Answer>`
-
-`state` is a string, object or array (serialized as JSON). `questions` is a map of question definitions:
-
-| type | `criteria` | answer |
-|---|---|---|
-| `choice` | object (label → meaning) or array | `{ type: 'choice', choice, probabilities, confidence }` |
-| `score` | array of ordered levels | `{ type: 'score', score, legend, probabilities, confidence }` |
-| `noul` | optional `{false, true}` text | `{ type: 'noul', noul, confidence, threshold?, decision? }` |
-
-`noul` returns `noul` ∈ [0,1] (probability of *true*). With a `threshold`, a boolean `decision` is added. All fields round to 4 decimals.
-
-### HTTP server
-
-```js
-import { serve } from 'laya-system-one';
-const srv = await serve({ port: 8080, apiKey: process.env.LAYA_API_KEY });
-console.log(srv.url);   // http://localhost:8080
-await srv.close();      // releases the engine and any child process
-```
-
-| endpoint | method | body | response |
-|---|---|---|---|
-| `/v1/systemone` | `POST` | `{ state, questions, model? }` | `{ model, answers, usage }` |
-| `/health` | `GET` | – | `{ status, model, backend, protocol }` |
-
-Errors: `401` missing/invalid API key, `422` invalid payload, `404` unknown route, `413` body over 4 MB.
-
-> The `native` backend runs its own internal HTTP server for the engine;
-> `serve()` keeps it on a private loopback port and never exposes it.
-
----
-
-## CLI
-
-```bash
-npx laya-system-one --port 8080 --backend native
-```
-
-```
---port <number>     HTTP port (default 8080, or PORT env)
---host <string>     bind address (default 0.0.0.0, or HOST env)
---backend <type>    native | wasm (default native)
---api-key <string>  require Bearer token auth
---help / --version
-```
-
----
-
-## Environment variables
-
-| variable | effect |
-|---|---|
-| `LAYA_BACKEND` | `native` \| `wasm` |
-| `LAYA_MODEL_PATH` | explicit `model.onnx` (file or directory) |
-| `LAYA_MODEL_CHUNKS_DIR` | directory with chunk files / chunk packages |
-| `LAYA_MODEL_URL` | override the download URL of the model asset |
-| `LAYA_CACHE_DIR` | where downloaded models are cached |
-| `LAYA_PREFETCH_MODEL` | `1` = fetch the model during `npm install` |
-| `LAYA_SKIP_MODEL_DOWNLOAD` | `1` = never download, never hint |
-| `LAYA_API_KEY` / `API_KEY` | require `Authorization: Bearer <key>` |
-| `LAYA_SERVE_BIN` | explicit path to the `laya-serve` binary |
-
----
-
-## Performance
-
-`npm run bench` measures it on your own hardware and writes a JSON report.
-
-Measured by CI on every platform we ship a binary for (the bundled
-`laya-serve` binary, 4 questions per call). Shared GitHub runners vary
-~20% between runs, so treat these as orders of magnitude, not promises -
-run `npm run bench` on your own hardware for exact numbers:
-
-| platform | init | cold question | warm avg (4 q) | warm p50 / p95 | 1 q per call | throughput |
-|---|---|---|---|---|---|---|
-| **linux-arm64** (musl) | 1.9 s | 247 ms | 154 ms | 143 / 205 | 36 ms | 28.1 q/s |
-| **linux-arm64** (glibc) | 1.6 s | 184 ms | 145 ms | 142 / 163 | 40 ms | 24.9 q/s |
-| **win-x64** | 1.7 s | 175 ms | 149 ms | 142 / 175 | 40 ms | 24.8 q/s |
-| **win-arm64** | 1.4 s | 231 ms | 178 ms | 174 / 204 | 47 ms | 21.2 q/s |
-| **mac-arm64** | 1.3 s | 268 ms | 220 ms | 218 / 250 | 51 ms | 19.5 q/s |
-| **linux-x64** (musl) | 2.3 s | 387 ms | 253 ms | 239 / 311 | 59 ms | 16.9 q/s |
-| **linux-x64** (glibc) | 2.5 s | 331 ms | 264 ms | 259 / 322 | 63 ms | 15.8 q/s |
-| **mac-x64** (Intel, ORT 1.23) | 2.9 s | 387 ms | 360 ms | 356 / 398 | 84 ms | 11.9 q/s |
-
-`init` is loading the model, `cold` is the very first question (warmup and
-arena allocation), and the warm numbers are the sustained latency.
-
-The `wasm` fallback is ~100x slower by design: `tract` specializes the whole
-model per input shape, so it runs a fixed padded shape (see
-`LayaEngine.padForWasm`) and pays for every position - about 6 s per question
-in the small bucket, 1.8 s to load. It exists for browsers and exotic
-platforms, not for throughput.
-
-**If you are on a platform we ship a binary for and you see the wasm backend
-being used, that is a bug** - the install is broken. The tests fail on
-purpose in that situation (`LAYA_ALLOW_WASM_FALLBACK=1` is the only way to
-accept the fallback).
-
-## Size
-
-| component | size |
-|---|---|
-| npm package | ~88 MB (native binaries for 6 platforms + WASM + tokenizer) |
-| model asset | ~324 MB (acquired once, cached, checksum-verified) |
-| disk after install + model | ~560 MB |
-| Docker (Debian slim + Bun + package) | ~450 MB image |
-
----
-
-## Requirements
-
-| | |
-|---|---|
-| **Node.js** | ≥ 18.17 (zero runtime dependencies) |
-| **Bun** | ≥ 1.0 (fully supported) |
-| **Browsers** | WASM backend (no install required) |
-| **OS** | Linux (glibc + musl/Alpine), macOS (arm64), Windows (x64 + arm64) |
-| **Docker** | works on Debian slim, Ubuntu, Alpine |
-
-The `native` backend needs nothing installed: the binary is statically linked and ships in the package (for musl/Alpine it ships as a single self-extracting bundle with its own `lib/`).
-
----
-
-## Storage
-
-| what | where | size |
-|---|---|---|
-| package (code + binaries) | `node_modules/laya-system-one` | ~88 MB unpacked |
-| model asset | `models/model.onnx` or `~/.cache/laya-system-one/` | ~324 MB |
-| chunk packages | `dist/release/model-chunks/` (release artifacts) | ~324 MB |
-
-The model is written to the package directory when it is writable, otherwise to the user cache — so global installs (`npm i -g`) and read-only containers work out of the box.
-
----
-
-## Development
-
-```bash
-npm install
-npm test                 # unit + packaging (fast, offline)
-npm run test:integration # real model + tokenizer
-npm run test:e2e         # HTTP protocol + CLI + lifecycle
-npm run test:install     # pack + install into a clean dir + run
-npm run smoke            # one-shot human-readable verification
-npm run lint             # syntax + packaging + docs consistency gate
-npm run tokenizer:diff   # prove the JS tokenizer == the native binary's
-```
-
-The model-distribution pipeline (the reason the 324 MB asset can live on npm):
-
-```bash
-npm run model:chunks      # split models/model.onnx into chunk packages
-npm run model:assemble    # reassemble from the chunks (byte-identical)
-npm run model:verify      # checksum the model against the manifest
-npm run model:publish     # publish the chunk packages to npm
-```
-
-CI runs the whole matrix (OS × Node) plus model-backed integration tests on every push — see `.github/workflows/ci.yml`.
-
-## Migrating from 1.0.0
-
-1.0.0 on npm was a different codebase (ONNX Runtime only, model embedded, single language). The `/v1/systemone` wire protocol is unchanged, so HTTP clients keep working. Node API changes:
-
-- `predict(state, questions)` takes a *map* of questions (1.0.0 took a single question and returned a bare value);
-- `server.js`/`client.js` were replaced by `serve()` + `Laya.load()`;
-- the model is no longer embedded in the package — it is acquired on first use (see above).
-
-## License
-
-Apache-2.0 — see [LICENSE](LICENSE).
+# Laya System-One ⚡
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Runtime](https://img.shields.io/badge/Runtime-Node.js%20%7C%20Bun%20%7C%20Browser-green.svg)]()
+[![TypeSafe Jev](https://img.shields.io/badge/Wire%20Protocol-TypeSafe%20Jev%20Compatible-orange.svg)]()
+[![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)]()
+
+> **A fast, self-contained decision engine. Give it any text and a set of typed questions, and it answers them — offline, in milliseconds, in over 100 languages. Drop-in compatible with the TypeSafe Jev API (`POST /v1/systemone`).**
+
+Runs entirely on your machine. No Python, no PyTorch, no API keys, no cloud
+calls at inference time. One `npm install` and it works.
+
+---
+
+## 🌟 Why Laya System-One?
+
+- 🔒 **100% Offline:** Nothing leaves your machine. Ideal for corporate
+  intranets, edge servers and privacy-sensitive workflows.
+- ⚡ **Fast:** ~40 ms per question on a warm engine, measured on every platform
+  we ship for.
+- 🔄 **TypeSafe Jev Compatible:** Drop-in `POST /v1/systemone`. Point an
+  existing Jev client at it and it just works.
+- 🌍 **Multilingual:** Understands English, Portuguese, Spanish, German,
+  French, Chinese, Japanese and 100+ more, out of the box.
+- 💻 **Node.js, Bun and Browsers:** Native binary on Node and Bun, WebAssembly
+  in the browser.
+- 📦 **Zero Dependencies:** `dependencies` is empty. Nothing to compile,
+  nothing to install system-wide, nothing to keep patched.
+- 🧩 **Two Ways to Run It:** As a local HTTP service via the CLI, or in-process
+  for zero network overhead.
+
+---
+
+## 📦 Installation
+
+```bash
+# npm
+npm install laya-system-one
+
+# bun
+bun add laya-system-one
+
+# pnpm
+pnpm add laya-system-one
+```
+
+The right engine for your machine is installed automatically. The model
+(~324 MB) is fetched once on first use and cached.
+
+---
+
+## 🚀 Quick Start
+
+### 1. Launch the HTTP service
+
+```bash
+npx laya-system-one --port 8080
+```
+
+| Flag | Env | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--port <number>` | `PORT` | `8080` | Port to bind |
+| `--host <string>` | `HOST` | `0.0.0.0` | Address to bind |
+| `--backend <type>` | `LAYA_BACKEND` | `native` | `native` or `wasm` |
+| `--api-key <token>` | `LAYA_API_KEY` | *(none)* | Require Bearer auth on `/v1/systemone` |
+
+With authentication:
+
+```bash
+npx laya-system-one --port 8080 --api-key secret-token-xyz
+```
+
+### 2. Use it in-process (zero network overhead)
+
+```javascript
+import { Laya } from 'laya-system-one';
+
+// 1. Initialize the engine
+const laya = await Laya.load();
+
+// 2. Define the state (string, object, or array)
+const state = {
+  customer_id: 'cust_9821',
+  message: 'We were charged twice on our March invoice. Please refund the duplicate amount or we will cancel our plan.'
+};
+
+// 3. Define typed questions
+const questions = {
+  department: {
+    type: 'choice',
+    instructions: 'Which team should resolve this customer inquiry?',
+    criteria: {
+      billing: 'Invoices, refunds, and duplicate charges',
+      tech_support: 'Software bugs, outages, and error messages',
+      sales: 'Upgrades, plan changes, and enterprise contracts'
+    }
+  },
+  urgency: {
+    type: 'score',
+    instructions: 'Assess the urgency level of this inquiry.',
+    criteria: ['Low / routine', 'Moderate', 'Critical / blocking / angry']
+  },
+  churn_risk: {
+    type: 'noul',
+    instructions: 'Does this message present an explicit risk of customer churn?',
+    threshold: 0.5
+  }
+};
+
+// 4. Evaluate
+const result = await laya.predict(state, questions);
+
+console.log(result.answers.department.choice);     // -> "billing"
+console.log(result.answers.department.confidence); // -> 1.0
+console.log(result.answers.urgency.score);         // -> 1.95
+console.log(result.answers.churn_risk.noul);       // -> 0.968
+console.log(result.answers.churn_risk.decision);   // -> true
+```
+
+### 3. Serve it from inside your app
+
+```javascript
+import { serve } from 'laya-system-one';
+
+const srv = await serve({ host: '127.0.0.1', port: 8080, apiKey: 'optional-key' });
+
+console.log(`Laya server running at ${srv.url}/v1/systemone`);
+
+// later:
+await srv.close();
+```
+
+---
+
+## 📡 HTTP API Reference (TypeSafe Jev compatible)
+
+```http
+POST /v1/systemone
+Host: localhost:8080
+Content-Type: application/json
+Authorization: Bearer <API_KEY>   [optional unless configured]
+```
+
+| Parameter | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `state` | `string` \| `object` \| `array` | **Yes** | The context or text being evaluated. |
+| `questions` | `Record<string, Question>` | **Yes** | Map of question keys to typed questions. |
+| `model` | `string` | No | Model name (defaults to `laya-multilingual`, echoed back). |
+
+### Question types
+
+**`choice`** — pick one of several options:
+
+```json
+{
+  "type": "choice",
+  "instructions": "Which department should handle this ticket?",
+  "criteria": {
+    "billing": "Invoices and credit card transactions",
+    "technical": "Software bugs and service disruptions"
+  }
+}
+```
+
+**`score`** — place on an ordered scale:
+
+```json
+{
+  "type": "score",
+  "instructions": "Rate the severity of the issue.",
+  "criteria": ["Minor cosmetic issue", "Degraded functionality", "Critical full service outage"]
+}
+```
+
+**`noul`** — calibrated yes/no probability:
+
+```json
+{
+  "type": "noul",
+  "instructions": "Does the user explicitly request a refund?",
+  "threshold": 0.6
+}
+```
+
+### Example request
+
+```bash
+curl -X POST http://localhost:8080/v1/systemone \
+  -H "Content-Type: application/json" \
+  -d '{
+    "state": { "text": "Fui cobrado duas vezes na minha fatura. Reembolsem imediatamente." },
+    "questions": {
+      "dept": {
+        "type": "choice",
+        "instructions": "Which department should respond?",
+        "criteria": { "billing": "Refunds, invoices, and payments", "support": "Technical and product questions" }
+      },
+      "urgency": {
+        "type": "score",
+        "instructions": "Urgency rating",
+        "criteria": ["Low", "Medium", "High"]
+      },
+      "refund_demanded": {
+        "type": "noul",
+        "instructions": "Is the customer requesting a refund?",
+        "threshold": 0.5
+      }
+    }
+  }'
+```
+
+### Example response
+
+```json
+{
+  "model": "laya-multilingual",
+  "answers": {
+    "dept": {
+      "type": "choice",
+      "choice": "billing",
+      "probabilities": { "billing": 1.0, "support": 0.0 },
+      "confidence": 1.0
+    },
+    "urgency": {
+      "type": "score",
+      "score": 1.9482,
+      "legend": { "0": "Low", "1": "Medium", "2": "High" },
+      "probabilities": { "0": 0.0011, "1": 0.0496, "2": 0.9493 },
+      "confidence": 0.9493
+    },
+    "refund_demanded": {
+      "type": "noul",
+      "noul": 0.9852,
+      "confidence": 0.9852,
+      "threshold": 0.5,
+      "decision": true
+    }
+  },
+  "usage": { "input_tokens": 82, "output_tokens": 12 }
+}
+```
+
+### Healthcheck
+
+```http
+GET /health
+```
+
+```json
+{
+  "status": "ok",
+  "model": "laya-multilingual",
+  "version": "1.1.0",
+  "protocol": "TypeSafe Jev /v1/systemone compatible"
+}
+```
+
+### Error codes
+
+- `401 Unauthorized` — API key configured, header missing or wrong.
+- `422 Unprocessable Entity` — invalid JSON, or `state`/`questions` missing.
+- `404 Not Found` — unknown route.
+- `413 Payload Too Large` — body over 4 MB.
+
+---
+
+## ⚙️ Backends
+
+| Backend | How it runs | When to use |
+| :--- | :--- | :--- |
+| **`native`** *(default)* | A self-contained Rust server bundled with the package | The normal choice. Fastest, nothing to install. |
+| **`wasm`** | Pure Rust compiled to WebAssembly, also bundled | Browsers, or platforms with no native build. |
+
+Both ship inside the package — nothing is compiled or downloaded at install
+time. Switch with `--backend wasm` or `LAYA_BACKEND=wasm`.
+
+---
+
+## 📊 Performance
+
+Measured on real hardware, on every platform we ship a binary for, with the
+default `native` backend. Run `npm run bench` to measure your own machine.
+
+| Platform | Load | First answer | Warm (4 q/call) | Per question |
+| :--- | ---: | ---: | ---: | ---: |
+| macOS arm64 | 1.3 s | 268 ms | 220 ms | 51 ms |
+| Windows arm64 | 1.4 s | 231 ms | 178 ms | 47 ms |
+| Linux arm64 | 1.6 s | 184 ms | 145 ms | 40 ms |
+| Windows x64 | 1.7 s | 175 ms | 149 ms | 40 ms |
+| Linux arm64 (musl) | 1.9 s | 247 ms | 154 ms | 36 ms |
+| Linux x64 (musl) | 2.3 s | 387 ms | 253 ms | 59 ms |
+| Linux x64 | 2.5 s | 331 ms | 264 ms | 63 ms |
+| macOS x64 | 2.9 s | 387 ms | 360 ms | 84 ms |
+
+`Load` is reading the model into memory. `First answer` includes warmup. The
+warm numbers are sustained latency. Shared CI runners vary by ~20% between
+runs, so treat these as orders of magnitude rather than exact figures.
+
+The `wasm` backend is roughly 100x slower — it exists so browsers and unusual
+platforms work at all, not for throughput.
+
+---
+
+## 🧾 Environment variables
+
+| Variable | Effect |
+| :--- | :--- |
+| `LAYA_BACKEND` | `native` or `wasm` |
+| `LAYA_MODEL_PATH` | Use a `model.onnx` you already have (file or directory) |
+| `LAYA_MODEL_CHUNKS_DIR` | Directory holding the model chunks |
+| `LAYA_MODEL_URL` | Override where the model is downloaded from |
+| `LAYA_CACHE_DIR` | Where the model is cached |
+| `LAYA_PREFETCH_MODEL` | `1` = download the model during `npm install` |
+| `LAYA_SKIP_MODEL_DOWNLOAD` | `1` = never download, never prompt |
+| `LAYA_API_KEY` / `API_KEY` | Require `Authorization: Bearer <key>` |
+| `LAYA_SERVE_BIN` | Use a specific `laya-serve` binary |
+
+**Offline or air-gapped:**
+
+```bash
+LAYA_PREFETCH_MODEL=1 npm install laya-system-one   # fetch during install
+LAYA_MODEL_PATH=/opt/models/model.onnx              # or bring your own copy
+LAYA_MODEL_CHUNKS_DIR=/opt/models/chunks            # or a directory of chunks
+```
+
+---
+
+## 💻 Requirements
+
+| | |
+| :--- | :--- |
+| **Node.js** | ≥ 18.17 |
+| **Bun** | ≥ 1.0 |
+| **Browsers** | The `wasm` backend |
+| **OS** | Linux (glibc and musl/Alpine), macOS (arm64 and x64), Windows (x64 and arm64) |
+| **Docker** | Debian, Ubuntu, Alpine |
+
+No runtime dependencies. The right native binary for your machine is installed
+automatically — nothing to compile, no system packages to add.
+
+---
+
+## 📥 What gets installed
+
+The package itself is small; the heavy parts arrive as dependencies npm picks
+for your platform, so you only download what you can run.
+
+| | Size |
+| :--- | ---: |
+| `laya-system-one` (code, tokenizer, wasm engine) | ~8.5 MB |
+| The one native binary for your platform | 8–26 MB |
+| The 13 model chunks | ~235 MB total |
+| The model on disk, after the first run | ~324 MB |
+
+The model is written next to the package when that directory is writable, and
+to your user cache otherwise — so `npm i -g` and read-only containers work
+without extra configuration. Every copy is checksum-verified, and a run that
+is killed mid-download leaves nothing corrupt behind.
+
+---
+
+## 🛠️ Development
+
+```bash
+npm install
+npm run check            # lint, unit, packaging, integration, e2e + install rehearsal
+npm run check:quick      # the same minus the model-backed suites
+npm run test:rehearsal   # install from a local registry and use it, Node + Bun
+npm run bench            # measure on this machine
+npm run lint             # syntax + packaging + docs consistency
+```
+
+CI builds every platform, proves each binary answers 10 questions, and uploads
+the packages as artifacts. `verify-published.yml` installs a published version
+from the real registry on every platform — Node and Bun, including Alpine for
+musl — and runs a real inference.
+
+---
+
+## 📄 License & Attribution
+
+- **License:** [Apache-2.0](LICENSE)
+- **Author:** [Italo Almeida](https://github.com/italoalmeida0)
+- **Repository:** [https://github.com/italoalmeida0/laya-system-one](https://github.com/italoalmeida0/laya-system-one)

package/models/model.manifest.json

@@ -10,91 +10,91 @@
     {
       "index": 0,
       "package": "@sys-one/laya-model-chunk-00",
-      "version": "1.1.0-alpha.0",
+      "version": "1.1.0",
       "bytes": 25165824,
       "sha256": "ef5fb331bbc913691ddb94c65efd4139bbad581870f00ceec697e27a1a277d68"
     },
     {
       "index": 1,
       "package": "@sys-one/laya-model-chunk-01",
-      "version": "1.1.0-alpha.0",
+      "version": "1.1.0",
       "bytes": 25165824,
       "sha256": "197cf82966fa114b1c5480d67dfb0c69e2a29b26d9cdd260a15d34ed7e94bc3d"
     },
     {
       "index": 2,
       "package": "@sys-one/laya-model-chunk-02",
-      "version": "1.1.0-alpha.0",
+      "version": "1.1.0",
       "bytes": 25165824,
       "sha256": "a72e60a93dfa4e93eedc45eb0bfc0c0ab48010db35d93acd613c2312e59c35e1"
     },
     {
       "index": 3,
       "package": "@sys-one/laya-model-chunk-03",
-      "version": "1.1.0-alpha.0",
+      "version": "1.1.0",
       "bytes": 25165824,
       "sha256": "7db3119f56cc6a4874b0c300effc06ae0f2e4587486d4c6673d74375157426b6"
     },
     {
       "index": 4,
       "package": "@sys-one/laya-model-chunk-04",
-      "version": "1.1.0-alpha.0",
+      "version": "1.1.0",
       "bytes": 25165824,
       "sha256": "b3c66e9ae3210f4a6b0e89e235e880b9eea6636afe33c90e21b07c4260dfea91"
     },
     {
       "index": 5,
       "package": "@sys-one/laya-model-chunk-05",
-      "version": "1.1.0-alpha.0",
+      "version": "1.1.0",
       "bytes": 25165824,
       "sha256": "eb659ce78d4deb34107eff20b86339d77f5fd4e2ae3ccad625775528cd376b6c"
     },
     {
       "index": 6,
       "package": "@sys-one/laya-model-chunk-06",
-      "version": "1.1.0-alpha.0",
+      "version": "1.1.0",
       "bytes": 25165824,
       "sha256": "9ac3fd26e588debb86e2368093e58272b9a318515b9eaebf07da8d1429dc5b62"
     },
     {
       "index": 7,
       "package": "@sys-one/laya-model-chunk-07",
-      "version": "1.1.0-alpha.0",
+      "version": "1.1.0",
       "bytes": 25165824,
       "sha256": "40c158c978ba8285a69b41282308f108d24390734660935be69c6b58ea186b6a"
     },
     {
       "index": 8,
       "package": "@sys-one/laya-model-chunk-08",
-      "version": "1.1.0-alpha.0",
+      "version": "1.1.0",
       "bytes": 25165824,
       "sha256": "d8ce88b2cc1c2f0bcb6f50414fb56741a21d3d2221db19c9fff8879f5e58668e"
     },
     {
       "index": 9,
       "package": "@sys-one/laya-model-chunk-09",
-      "version": "1.1.0-alpha.0",
+      "version": "1.1.0",
       "bytes": 25165824,
       "sha256": "a83210739f94a9ffbf99c32aedd6e8ac68bcbe8be42d57485fff9534e2d8011b"
     },
     {
       "index": 10,
       "package": "@sys-one/laya-model-chunk-10",
-      "version": "1.1.0-alpha.0",
+      "version": "1.1.0",
       "bytes": 25165824,
       "sha256": "c06ed434512a4a8d610d27f52a91bdfff46001eab2b586f11d65c506140753f0"
     },
     {
       "index": 11,
       "package": "@sys-one/laya-model-chunk-11",
-      "version": "1.1.0-alpha.0",
+      "version": "1.1.0",
       "bytes": 25165824,
       "sha256": "44a0a9ad824ab26b8a1c5edb2d71c7283341e4bee5e1bfa4de2a4a9a813e9081"
     },
     {
       "index": 12,
       "package": "@sys-one/laya-model-chunk-12",
-      "version": "1.1.0-alpha.0",
+      "version": "1.1.0",
       "bytes": 22135720,
       "sha256": "35e2c872c113e76456e6790f08c9714f2b83f8a049a550814efd5355640df5ce"
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "laya-system-one",
-  "version": "1.1.0-alpha.0",
+  "version": "1.1.0",
   "description": "Self-contained System 1 decision engine: multilingual INT8 transformer served by a zero-dependency native binary (or the bundled pure-Rust WASM engine). TypeSafe Jev wire-compatible (/v1/systemone). Runs offline in Node.js, Bun and browsers.",
   "main": "./src/index.js",
   "module": "./src/index.js",
@@ -79,25 +79,25 @@
   "homepage": "https://github.com/italoalmeida0/laya-system-one#readme",
   "dependencies": {},
   "optionalDependencies": {
-    "@sys-one/laya-serve-darwin-arm64": "1.1.0-alpha.0",
-    "@sys-one/laya-serve-darwin-x64": "1.1.0-alpha.0",
-    "@sys-one/laya-serve-win32-x64": "1.1.0-alpha.0",
-    "@sys-one/laya-serve-win32-arm64": "1.1.0-alpha.0",
-    "@sys-one/laya-serve-linux-x64": "1.1.0-alpha.0",
-    "@sys-one/laya-serve-linux-arm64": "1.1.0-alpha.0",
-    "@sys-one/laya-serve-universal": "1.1.0-alpha.0",
-    "@sys-one/laya-model-chunk-00": "1.1.0-alpha.0",
-    "@sys-one/laya-model-chunk-01": "1.1.0-alpha.0",
-    "@sys-one/laya-model-chunk-02": "1.1.0-alpha.0",
-    "@sys-one/laya-model-chunk-03": "1.1.0-alpha.0",
-    "@sys-one/laya-model-chunk-04": "1.1.0-alpha.0",
-    "@sys-one/laya-model-chunk-05": "1.1.0-alpha.0",
-    "@sys-one/laya-model-chunk-06": "1.1.0-alpha.0",
-    "@sys-one/laya-model-chunk-07": "1.1.0-alpha.0",
-    "@sys-one/laya-model-chunk-08": "1.1.0-alpha.0",
-    "@sys-one/laya-model-chunk-09": "1.1.0-alpha.0",
-    "@sys-one/laya-model-chunk-10": "1.1.0-alpha.0",
-    "@sys-one/laya-model-chunk-11": "1.1.0-alpha.0",
-    "@sys-one/laya-model-chunk-12": "1.1.0-alpha.0"
+    "@sys-one/laya-serve-darwin-arm64": "1.1.0",
+    "@sys-one/laya-serve-darwin-x64": "1.1.0",
+    "@sys-one/laya-serve-win32-x64": "1.1.0",
+    "@sys-one/laya-serve-win32-arm64": "1.1.0",
+    "@sys-one/laya-serve-linux-x64": "1.1.0",
+    "@sys-one/laya-serve-linux-arm64": "1.1.0",
+    "@sys-one/laya-serve-universal": "1.1.0",
+    "@sys-one/laya-model-chunk-00": "1.1.0",
+    "@sys-one/laya-model-chunk-01": "1.1.0",
+    "@sys-one/laya-model-chunk-02": "1.1.0",
+    "@sys-one/laya-model-chunk-03": "1.1.0",
+    "@sys-one/laya-model-chunk-04": "1.1.0",
+    "@sys-one/laya-model-chunk-05": "1.1.0",
+    "@sys-one/laya-model-chunk-06": "1.1.0",
+    "@sys-one/laya-model-chunk-07": "1.1.0",
+    "@sys-one/laya-model-chunk-08": "1.1.0",
+    "@sys-one/laya-model-chunk-09": "1.1.0",
+    "@sys-one/laya-model-chunk-10": "1.1.0",
+    "@sys-one/laya-model-chunk-11": "1.1.0",
+    "@sys-one/laya-model-chunk-12": "1.1.0"
   }
 }

package/src/laya-native.js

@@ -122,12 +122,17 @@ function binaryCandidates() {
   const exe = plat === 'win32' ? 'laya-serve.exe' : 'laya-serve';
   const slots = [];
   for (const arch of arches) {
-    if (plat === 'linux') slots.push(`linux-${arch}-musl`);
-    if (musl) continue; // never fall back to a glibc binary on musl
-    slots.push(`${plat}-${arch}`);
+    // Order matters, and libc decides it: on musl only the musl bundle can
+    // load (the glibc binary has no interpreter), and on glibc the musl
+    // bundle is the wrong build. Never probe both - the earlier version
+    // pushed the musl slot first on every Linux, so a glibc machine picked
+    // the musl bundle and died with "exited before ready".
+    if (plat === 'linux') {
+      slots.push(musl ? `linux-${arch}-musl` : `linux-${arch}`);
+    } else {
+      slots.push(`${plat}-${arch}`);
+    }
   }
-  // the universal package stores glibc builds under the plain slot too, so a
-  // non-musl loop above already covers it; nothing extra to add here.
   return { exe, slots };
 }
 

package/src/server.js

@@ -1,179 +1,194 @@
-import http from 'node:http';
-import { Laya } from './agent.js';
-
-/**
- * Start HTTP server exposing the TypeSafe Jev /v1/systemone wire protocol.
- * @param {Object} options - Server options:
- *   - host: string (default: '0.0.0.0' or process.env.HOST)
- *   - port: number (default: 8080 or process.env.PORT)
- *   - apiKey: string (optional, or process.env.LAYA_API_KEY / process.env.API_KEY)
- *   - laya: preloaded Laya instance (optional)
- *   - device: 'auto' | 'webgpu' | 'wasm' | 'cpu' (default: 'auto')
- * @returns {Promise<{ server: http.Server, url: string, laya: object, close: Function }>}
- */
-export async function serve(options = {}) {
-  const host = options.host || process.env.HOST || '0.0.0.0';
-  // `port: 0` means "pick a free port" — it must not be treated as unset.
-  const portRaw = options.port ?? process.env.PORT;
-  const parsed = Number.parseInt(portRaw ?? '8080', 10);
-  const port = Number.isFinite(parsed) ? parsed : 8080;
-  const apiKey = options.apiKey || process.env.LAYA_API_KEY || process.env.API_KEY || null;
-  // When we create the engine ourselves we also own its lifecycle: close()
-  // must release it (the native backend spawns a laya-serve child process —
-  // leaving it alive keeps the Node event loop busy and the process hangs
-  // forever after the HTTP server is done).
-  const ownsLaya = !options.laya;
-  // The engine runs its own internal HTTP server (native backend). It must
-  // never share the public port: on Windows two sockets CAN bind the same
-  // address (SO_REUSEADDR), so requests would reach the wrong server and
-  // shutdown would look broken. Keep it on a private loopback port.
-  const laya = options.laya || (await Laya.load({ ...options, host: '127.0.0.1', port: 0 }));
-
-  // End-to-end warmup: first real predict() pays tokenizer-cache fill +
-  // any remaining lazy init. Do it once at startup (best-effort) so the
-  // first Tetris piece doesn't eat the cold-start cost.
-  if (!options.laya && options.warmup !== false) {
-    try {
-      await laya.predict('warmup', { w: { type: 'noul', instructions: 'warmup probe' } });
-    } catch { /* best-effort */ }
-  }
-
-  const server = http.createServer((req, res) => {
-    // Standard CORS headers
-    res.setHeader('Access-Control-Allow-Origin', '*');
-    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
-    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
-
-    // Handle preflight OPTIONS request
-    if (req.method === 'OPTIONS') {
-      res.writeHead(204);
-      res.end();
-      return;
-    }
-
-    const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
-
-    // Healthcheck endpoint
-    if (req.method === 'GET' && (url.pathname === '/' || url.pathname === '/health')) {
-      res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({
-        status: 'ok',
-        model: 'laya-multilingual',
-        version: '1.0.0',
-        protocol: 'TypeSafe Jev /v1/systemone compatible'
-      }));
-      return;
-    }
-
-    // TypeSafe Jev evaluation endpoint
-    if (req.method === 'POST' && url.pathname === '/v1/systemone') {
-      // Optional bearer token authentication
-      if (apiKey) {
-        const authHeader = req.headers['authorization'] || '';
-        if (authHeader !== `Bearer ${apiKey}`) {
-          res.writeHead(401, { 'Content-Type': 'application/json' });
-          res.end(JSON.stringify({
-            error: 'Unauthorized: missing or invalid bearer token in Authorization header.'
-          }));
-          return;
-        }
-      }
-
-      const chunks = [];
-      let size = 0;
-      req.on('data', chunk => {
-        chunks.push(chunk);
-        size += chunk.length;
-        if (size > 4 * 1024 * 1024) { // 4MB guard
-          res.writeHead(413, { 'Content-Type': 'application/json' });
-          res.end(JSON.stringify({ error: 'Payload too large (max 4MB).' }));
-          req.destroy();
-        }
-      });
-
-      req.on('end', async () => {
-        let payload;
-        try {
-          payload = JSON.parse(Buffer.concat(chunks).toString('utf8'));
-        } catch (e) {
-          res.writeHead(422, { 'Content-Type': 'application/json' });
-          res.end(JSON.stringify({
-            error: 'Unprocessable Entity: invalid JSON payload.'
-          }));
-          return;
-        }
-
-        const state = payload.state;
-        const questions = payload.questions;
-        const requestedModel = payload.model || null;
-
-        if (state === undefined || state === null) {
-          res.writeHead(422, { 'Content-Type': 'application/json' });
-          res.end(JSON.stringify({
-            error: "Unprocessable Entity: missing required 'state' field."
-          }));
-          return;
-        }
-
-        if (!questions || typeof questions !== 'object' || Array.isArray(questions)) {
-          res.writeHead(422, { 'Content-Type': 'application/json' });
-          res.end(JSON.stringify({
-            error: "Unprocessable Entity: 'questions' must be an object map of typed questions."
-          }));
-          return;
-        }
-
-        try {
-          const result = await laya.predict(state, questions, requestedModel);
-          res.writeHead(200, { 'Content-Type': 'application/json' });
-          res.end(JSON.stringify(result));
-        } catch (err) {
-          res.writeHead(422, { 'Content-Type': 'application/json' });
-          res.end(JSON.stringify({
-            error: `Evaluation failed: ${err.message || err}`
-          }));
-        }
-      });
-      return;
-    }
-
-    // 404 handler
-    res.writeHead(404, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({
-      error: `Not found: ${req.method} ${url.pathname}. Expected POST /v1/systemone`
-    }));
-  });
-
-  // Keep-alive tuning: game clients (Tetris) fire one request per piece on
-  // the same connection. Long keep-alive avoids TCP+handshake per move.
-  server.keepAliveTimeout = 65000;
-  server.headersTimeout = 66000;
-  server.requestTimeout = 0;
-  server.maxRequestsPerSocket = 0;
-
-  return new Promise((resolve, reject) => {
-    server.listen(port, host, () => {
-      const displayHost = host === '0.0.0.0' ? 'localhost' : host;
-      // use the port actually bound (0 means "any free port")
-      const boundPort = server.address()?.port ?? port;
-      const url = `http://${displayHost}:${boundPort}`;
-      resolve({
-        server,
-        url,
-        laya,
-        close: async () => {
-          await new Promise((resolve) => {
-            server.close(() => resolve());
-            // Node keeps idle keep-alive sockets open (undici pools them for
-            // seconds), which would block server.close() — force them shut so
-            // shutdown is immediate and deterministic.
-            server.closeIdleConnections?.();
-            server.closeAllConnections?.();
-          });
-          if (ownsLaya && typeof laya.close === 'function') await laya.close();
-        }
-      });
-    });
-    server.on('error', reject);
-  });
-}
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Laya } from './agent.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Report the version we actually are, not a literal that goes stale: /health
+// is what a deployment checks, and it said 1.0.0 while the package was 1.1.0.
+const PKG_VERSION = (() => {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')).version;
+  } catch {
+    return 'unknown';
+  }
+})();
+
+/**
+ * Start HTTP server exposing the TypeSafe Jev /v1/systemone wire protocol.
+ * @param {Object} options - Server options:
+ *   - host: string (default: '0.0.0.0' or process.env.HOST)
+ *   - port: number (default: 8080 or process.env.PORT)
+ *   - apiKey: string (optional, or process.env.LAYA_API_KEY / process.env.API_KEY)
+ *   - laya: preloaded Laya instance (optional)
+ *   - device: 'auto' | 'webgpu' | 'wasm' | 'cpu' (default: 'auto')
+ * @returns {Promise<{ server: http.Server, url: string, laya: object, close: Function }>}
+ */
+export async function serve(options = {}) {
+  const host = options.host || process.env.HOST || '0.0.0.0';
+  // `port: 0` means "pick a free port" — it must not be treated as unset.
+  const portRaw = options.port ?? process.env.PORT;
+  const parsed = Number.parseInt(portRaw ?? '8080', 10);
+  const port = Number.isFinite(parsed) ? parsed : 8080;
+  const apiKey = options.apiKey || process.env.LAYA_API_KEY || process.env.API_KEY || null;
+  // When we create the engine ourselves we also own its lifecycle: close()
+  // must release it (the native backend spawns a laya-serve child process —
+  // leaving it alive keeps the Node event loop busy and the process hangs
+  // forever after the HTTP server is done).
+  const ownsLaya = !options.laya;
+  // The engine runs its own internal HTTP server (native backend). It must
+  // never share the public port: on Windows two sockets CAN bind the same
+  // address (SO_REUSEADDR), so requests would reach the wrong server and
+  // shutdown would look broken. Keep it on a private loopback port.
+  const laya = options.laya || (await Laya.load({ ...options, host: '127.0.0.1', port: 0 }));
+
+  // End-to-end warmup: first real predict() pays tokenizer-cache fill +
+  // any remaining lazy init. Do it once at startup (best-effort) so the
+  // first Tetris piece doesn't eat the cold-start cost.
+  if (!options.laya && options.warmup !== false) {
+    try {
+      await laya.predict('warmup', { w: { type: 'noul', instructions: 'warmup probe' } });
+    } catch { /* best-effort */ }
+  }
+
+  const server = http.createServer((req, res) => {
+    // Standard CORS headers
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+
+    // Handle preflight OPTIONS request
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+
+    // Healthcheck endpoint
+    if (req.method === 'GET' && (url.pathname === '/' || url.pathname === '/health')) {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        status: 'ok',
+        model: 'laya-multilingual',
+        version: PKG_VERSION,
+        protocol: 'TypeSafe Jev /v1/systemone compatible'
+      }));
+      return;
+    }
+
+    // TypeSafe Jev evaluation endpoint
+    if (req.method === 'POST' && url.pathname === '/v1/systemone') {
+      // Optional bearer token authentication
+      if (apiKey) {
+        const authHeader = req.headers['authorization'] || '';
+        if (authHeader !== `Bearer ${apiKey}`) {
+          res.writeHead(401, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({
+            error: 'Unauthorized: missing or invalid bearer token in Authorization header.'
+          }));
+          return;
+        }
+      }
+
+      const chunks = [];
+      let size = 0;
+      req.on('data', chunk => {
+        chunks.push(chunk);
+        size += chunk.length;
+        if (size > 4 * 1024 * 1024) { // 4MB guard
+          res.writeHead(413, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Payload too large (max 4MB).' }));
+          req.destroy();
+        }
+      });
+
+      req.on('end', async () => {
+        let payload;
+        try {
+          payload = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        } catch (e) {
+          res.writeHead(422, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({
+            error: 'Unprocessable Entity: invalid JSON payload.'
+          }));
+          return;
+        }
+
+        const state = payload.state;
+        const questions = payload.questions;
+        const requestedModel = payload.model || null;
+
+        if (state === undefined || state === null) {
+          res.writeHead(422, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({
+            error: "Unprocessable Entity: missing required 'state' field."
+          }));
+          return;
+        }
+
+        if (!questions || typeof questions !== 'object' || Array.isArray(questions)) {
+          res.writeHead(422, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({
+            error: "Unprocessable Entity: 'questions' must be an object map of typed questions."
+          }));
+          return;
+        }
+
+        try {
+          const result = await laya.predict(state, questions, requestedModel);
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify(result));
+        } catch (err) {
+          res.writeHead(422, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({
+            error: `Evaluation failed: ${err.message || err}`
+          }));
+        }
+      });
+      return;
+    }
+
+    // 404 handler
+    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      error: `Not found: ${req.method} ${url.pathname}. Expected POST /v1/systemone`
+    }));
+  });
+
+  // Keep-alive tuning: game clients (Tetris) fire one request per piece on
+  // the same connection. Long keep-alive avoids TCP+handshake per move.
+  server.keepAliveTimeout = 65000;
+  server.headersTimeout = 66000;
+  server.requestTimeout = 0;
+  server.maxRequestsPerSocket = 0;
+
+  return new Promise((resolve, reject) => {
+    server.listen(port, host, () => {
+      const displayHost = host === '0.0.0.0' ? 'localhost' : host;
+      // use the port actually bound (0 means "any free port")
+      const boundPort = server.address()?.port ?? port;
+      const url = `http://${displayHost}:${boundPort}`;
+      resolve({
+        server,
+        url,
+        laya,
+        close: async () => {
+          await new Promise((resolve) => {
+            server.close(() => resolve());
+            // Node keeps idle keep-alive sockets open (undici pools them for
+            // seconds), which would block server.close() — force them shut so
+            // shutdown is immediate and deterministic.
+            server.closeIdleConnections?.();
+            server.closeAllConnections?.();
+          });
+          if (ownsLaya && typeof laya.close === 'function') await laya.close();
+        }
+      });
+    });
+    server.on('error', reject);
+  });
+}