arbitype 0.6.0__tar.gz

arbitype-0.6.0/.env.example

@@ -0,0 +1,15 @@
+# Copy these into the environment of the MCP process. Never commit a real key.
+TYPESAFE_API_KEY=
+# Optional overrides:
+# TYPESAFE_BASE_URL=https://api.typesafe.ai
+# TYPESAFE_DEFAULT_MODEL=jev-latest
+# TYPESAFE_TIMEOUT_SECONDS=10
+# TYPESAFE_MAX_RETRIES=2
+# TYPESAFE_RETRY_BACKOFF_SECONDS=0.5
+# TYPESAFE_MAX_BACKOFF_SECONDS=20
+# TYPESAFE_RETRY_JITTER=0.25
+# TYPESAFE_MAX_STATE_CHARS=120000
+# TYPESAFE_MAX_QUESTION_CHARS=60000
+# TYPESAFE_MAX_REQUEST_BYTES=512000
+# TYPESAFE_MAX_RESPONSE_BYTES=4194304
+# TYPESAFE_MAX_QUESTIONS=64

arbitype-0.6.0/BENCHMARK.md

@@ -0,0 +1,120 @@
+# Arbitype engineering comparison and verification
+
+This document records the engineering comparison and local verification used
+for the 0.6.0 release.
+The repositories were inspected through their public source, documentation,
+and test layouts on 2026-09-21. GitHub star counts are only a snapshot, not a
+quality ranking. This project was also exercised against the real TypeSafe API
+with short, controlled Jev requests; the credential was never printed or
+committed.
+
+## Professional MCP baselines
+
+| Project | Production practice observed | Decision for Arbitype |
+| --- | --- | --- |
+| [modelcontextprotocol/python-sdk](https://github.com/modelcontextprotocol/python-sdk) | Official Python SDK (24k stars at review time), typed protocol surface, 2026-07-28 plus earlier revisions, stdio/Streamable HTTP/SSE, discovery, and a real `Client` | Keep the runtime dependency-free; implement dual-era STDIO negotiation, precise schemas, and run the official SDK v2 against this server in CI. HTTP remains an explicit gap |
+| [PrefectHQ/fastmcp](https://github.com/PrefectHQ/fastmcp) | Mature Python framework (27k stars), server/client/app abstractions, generated schemas, auth/transports, async fixtures, typing and broad tests | Do not introduce a framework dependency for Arbitype's narrow service; adopt its contract-first schemas, bounded async/interoperability tests, and documentation discipline |
+| [modelcontextprotocol/inspector](https://github.com/modelcontextprotocol/inspector) | Official web/CLI/TUI inspector (10k stars), composable test servers, smoke tests, packaging guards, and CI quality gates | Keep this repository focused on Jev; add a scriptable official-SDK smoke test that can also be driven by Inspector/MCPJam |
+| [MCPJam/inspector](https://github.com/MCPJam/inspector) | Cross-client/model evals, OAuth debugging, traces, conformance checks, and CI regression gates | Arbitype exposes stable tools/output schemas for inspection, but does not pretend to replace cross-client eval or OAuth tooling |
+| [snyk/agent-scan](https://github.com/snyk/agent-scan) | Explicit consent before executing discovered STDIO commands, agent config discovery, prompt-injection and secret-risk scanning, signed release artifacts | Treat this adapter as read-only and secret-conscious, but do not claim to be a supply-chain scanner; users should scan untrusted MCP configs separately |
+
+The main trade-off is intentional: the official SDK and FastMCP provide a
+broader protocol surface and stronger reusable abstractions, while Arbitype
+keeps a zero-runtime-dependency footprint, a small auditable codebase, and a
+focused TypeSafe tool contract. That makes it easy to start on a constrained
+agent host, but means new MCP protocol features must be tracked and implemented
+here instead of inherited from an SDK.
+
+## Capability gap matrix
+
+| Area | Arbitype 0.6.0 | Professional baseline | Assessment |
+| --- | --- | --- | --- |
+| MCP protocol | 2026-07-28 modern STDIO metadata plus legacy initialize revisions; `server/discover`; version errors | Official SDK supports the current revision and earlier revisions | Strong for local STDIO; verified with the official SDK v2 |
+| Transports | Newline-delimited STDIO only | Official SDK/FastMCP/Inspector support Streamable HTTP and often SSE | Deliberate limitation; remote deployment needs a separate transport layer |
+| Server features | Tools only; resources/prompts are not advertised | Frameworks commonly expose tools, resources, prompts, subscriptions, elicitation | Correctly narrow for Jev; do not add unused surface just for parity |
+| Schemas | Strict input validation and per-tool output schemas | Generated or typed schemas plus runtime validation | Competitive for this fixed contract |
+| Reliability | Bounded retries, `Retry-After`, size limits, redaction, fail-closed provider validation | Mature projects add async cancellation, tracing, and broader fault injection | Good local reliability; cancellation/telemetry remain next steps |
+| Testing | 62 offline tests, subprocess lifecycle tests, real provider check, official SDK v2 smoke in CI | Large projects add conformance suites, cross-client evals, coverage gates | Above a typical small server; not a replacement for cross-client evaluation |
+| Security | Environment-only secret, read-only annotations, no file/command execution, bounded diagnostics | HTTP servers add OAuth, token audience checks, sandboxing and scanners | Safe for local STDIO; not an authenticated remote service |
+| Release engineering | Matrix CI, wheel inspection, clean install, compatibility aliases | Mature projects add signed artifacts, automated publishing, dependency/update gates | Solid foundation; signed releases and registry publishing remain |
+
+## Jev-specific community projects previously reviewed
+
+| Project | What it does well | What we kept out or changed |
+| --- | --- | --- |
+| [jkudish/jev-mcp](https://github.com/jkudish/jev-mcp) | Purpose-built tools, response validation, mock tests, useful review/gate vocabulary | It has a larger Node dependency tree; Arbitype keeps a smaller standard-library runtime and a raw API escape hatch |
+| [itsmostafa/typesafe-mcp](https://github.com/itsmostafa/typesafe-mcp) | Very simple single-tool Go binary, retry and batching ideas, straightforward host setup | Go is not available on every host; Arbitype keeps a Python-only install and adds higher-level tools without hiding the raw request |
+| [burnigtm/jev-mcp](https://github.com/burnigtm/jev-mcp) | Strong limits, cancellation, prepared calls, review and coding-loop policies, extensive tests | Its policy layer is intentionally opinionated and broad; Arbitype does not claim to authorize tool calls or spend on another model |
+| [Brainwires/jevwire](https://github.com/Brainwires/jevwire) | A deep Claude Code harness, hooks, daemon tests, tripwires, and gate policy | Hooks and a daemon are beyond Arbitype's minimal cross-client service; `gate` here is a pure result transformation, not an interception hook |
+| [blakestone-x/jev-mcp](https://github.com/blakestone-x/jev-mcp) | Typed tools, recipes, request budgets, registration scripts, security notes | Its current test run in this environment had 45 failures caused by an SDK/API boundary mismatch; Arbitype validates its own HTTP response contract independently |
+| [shaharia-lab/jev-cli](https://github.com/shaharia-lab/jev-cli) | Excellent CLI ergonomics, signed installers, CI-oriented exit codes and schemas | Rust was not installed in this environment; Arbitype provides a smaller Python CLI and package entry point |
+
+## Local results
+
+- Arbitype: 62 offline tests passed, followed by real Jev requests through
+  the MCP STDIO process. The live response returned `jev-1.13.0`, all three
+  question types, and token usage; response validation accepted it.
+- `@jkudish/jev-mcp`: build and unit/mock suite passed (the repository's
+  live end-to-end test was not run).
+- `burnigtm/jev-mcp`: build and its test runner passed: 141 tests, 139 passed,
+  2 skipped.
+- `jevwire`: build and full Vitest suite passed: 1,461 tests.
+- `blakestone-x/jev-mcp`: packaging completed, but its test suite reported
+  45 failures, 29 passes, and 4 skips in this environment. The failures
+  clustered around the installed `typesafe-sdk` response/error boundary and
+  stdio fixtures; they are recorded here rather than silently calling it a
+  pass.
+- Go and Rust projects could be inspected but not compiled because this host
+  does not have `go` or `cargo` installed.
+
+## Host and protocol verification
+
+- 62 local unit and integration tests pass with no network access and no API key.
+- A real subprocess STDIO handshake was exercised through `initialize`,
+  `notifications/initialized`, `tools/list`, `health`, and `shutdown`.
+- A modern `server/discover` request and per-request `2026-07-28` metadata path
+  were exercised, including `resultType`, cache metadata, and unsupported-version
+  errors.
+- The official MCP Python SDK v2 connected to the server, negotiated
+  `2026-07-28`, listed all 9 tools, and called `health` successfully.
+- The initialization instructions are 484 characters, below the 512-character
+  self-contained prefix limit used by the Codex integration.
+- Codex CLI 0.155.1 can list and inspect the configured `arbitype` STDIO server;
+  the server advertises only its actual `tools` capability. The wire contract
+  itself is host-neutral and uses standard MCP STDIO messages.
+- The wheel was built and installed in an isolated virtual environment, then
+  its version, canonical/legacy import identity, and MCP initialization were
+  checked.
+- The PEP 517 build path was exercised after removing the source-tree import
+  assumption from `setup.py`; clean isolated builds no longer depend on the
+  checkout being importable.
+- The default HTTP attempt timeout is 10 seconds, matching the official
+  TypeSafe Python SDK and leaving room for bounded retry behavior under common
+  MCP host tool timeouts.
+- Live checks remain explicit paid operations; CI continues to use local fakes
+  and never receives a provider credential.
+
+## Remaining priorities
+
+1. Add an optional Streamable HTTP deployment package with MCP OAuth discovery;
+   keep it separate from the zero-dependency STDIO core.
+2. Add Inspector/MCPJam-compatible cross-client smoke fixtures and a small
+   non-paid evaluation corpus for tool-selection regressions.
+3. Add structured cancellation and tracing if Jev requests become concurrent or
+   long-running; the current synchronous STDIO loop intentionally keeps the
+   failure surface small.
+
+These are repository smoke-test results, not a quality ranking or a claim that
+one project is safer for every deployment.
+
+## Arbitype design decisions
+
+1. Keep `evaluate` close to TypeSafe's official `POST /v1/systemone` contract.
+2. Validate before network calls and validate again before returning provider
+   data to an agent.
+3. Prefer bounded, explicit failure over “best effort” approval.
+4. Keep retry behavior transparent and respect `Retry-After`.
+5. Never put the API key in MCP arguments, stdout, or normal error details.
+6. Make the useful convenience tools deterministic wrappers, not hidden agent
+   loops or permission systems.
+7. Keep real-provider tests manual and opt-in; never put a paid live call in CI.

arbitype-0.6.0/CHANGELOG.md

@@ -0,0 +1,111 @@
+# Changelog
+
+## 0.6.0 — 2026-09-22
+
+### Renamed to Arbitype
+
+The project formerly known as TypeSafe MCP is now Arbitype. Arbitype is
+positioned as a typed decision layer for AI agents rather than a
+TypeSafe-specific MCP bridge.
+
+Canonical identities:
+
+- GitHub: `Renwang-Huang/arbitype`
+- PyPI: `arbitype`
+- CLI: `arbitype`
+- Python: `arbitype`
+- MCP Registry: `io.github.Renwang-Huang/arbitype`
+
+Legacy names remain available as compatibility aliases where practical. The
+former `typesafe-mcp` PyPI project and Registry identity are not deleted or
+overwritten by this source migration.
+
+- Moved the implementation to the canonical `arbitype` package and retained
+  module-level identity shims for `typesafe_mcp` and `typesafe_codex_mcp`.
+- Added the `arbitype` CLI and PyPI metadata while retaining both legacy CLI
+  aliases.
+- Updated MCP Registry, README, CI, release, and ecosystem-check metadata to
+  the Arbitype identity.
+- Verified that a same-name metadata-only `typesafe-mcp` migration wheel can
+  leave legacy console scripts stale during pip upgrades; the release keeps
+  the old PyPI project untouched and documents the safe uninstall-then-install
+  migration instead.
+
+## 0.5.3 — 2026-09-22
+
+- Bound STDIO frame reads to 16 MiB and discard oversized lines without
+  allocating the complete input; invalid UTF-8 now returns JSON-RPC parse
+  error `-32700` without terminating the server.
+- Enforced modern per-request MCP metadata, integer-only JSON-RPC request IDs,
+  and invalid explicit `params: null` handling while retaining legacy
+  handshake compatibility.
+- Added runtime validation for every advertised tool input and restricted
+  custom HTTP API endpoints to loopback hosts; remote endpoints must use
+  HTTPS.
+- Added provider-semantic preflight checks for Noul content and non-null Score
+  levels, preventing known TypeSafe 400/422 responses after a paid request.
+- Disabled automatic HTTP redirects so bearer credentials are never forwarded
+  to a redirect target.
+- Converted deeply nested or otherwise invalid JSON input into JSON-RPC parse
+  error `-32700` without terminating the STDIO server.
+
+## 0.5.2 — 2026-09-21
+
+- Published the `typesafe-mcp` distribution to PyPI for direct `uvx` installs.
+- Added official MCP Registry metadata and PyPI ownership verification.
+
+## 0.5.1 — 2026-09-21
+
+- Made the canonical-versus-legacy package layout explicit in the README and
+  compatibility module docstrings; `typesafe_mcp` remains the only
+  implementation package.
+- Centralized the package version and strengthened the official SDK smoke test
+  so it checks all 9 advertised tools, including `score`.
+- Fixed isolated PEP 517 wheel builds so packaging does not import the source
+  package before it has been installed.
+
+## 0.5.0 — 2026-09-21
+
+- Added MCP 2026-07-28 STDIO discovery and per-request metadata support while
+  retaining the legacy initialize handshake.
+- Added protocol version negotiation errors, modern `resultType` responses, and
+  cache metadata for list operations.
+- Replaced generic tool output objects with precise output schemas.
+- Added malformed JSON-RPC/id boundary tests and an official MCP Python SDK v2
+  interoperability smoke test in CI.
+
+## 0.4.0 — 2026-09-21
+
+- Rebranded the public project as TypeSafe MCP and renamed the distribution and
+  primary CLI to `typesafe-mcp`.
+- Added the neutral `typesafe_mcp` import path and retained the old package and
+  command as compatibility aliases.
+- Renamed the advertised `route` and `review` tools so the protocol contract is
+  not tied to one agent host; the old `codex_route` and `codex_review` calls are
+  accepted as migration aliases.
+- Reworked the documentation and host guidance for Codex, Claude, Cursor, VS
+  Code, and other MCP-capable clients without adding host-specific runtime code.
+
+## 0.3.0 — 2026-09-21
+
+- Narrowed the product contract to a Codex-first stdio MCP service.
+- Added Codex-oriented `codex_route`, `codex_review`, and non-network `health` tools.
+- Added read-only/idempotent MCP tool annotations and a Codex-focused initialization guide.
+- Removed unsupported resource and prompt capabilities and implemented the MCP shutdown/exit lifecycle.
+- Added safer handling for unexpected tool failures.
+- Aligned request/response validation with the official API, including structured null entries,
+  required model/usage fields, probability-weighted Score validation, and a 10-second default timeout.
+
+## 0.2.0 — 2026-09-21
+
+- Added a reusable standard-library TypeSafe client with bounded retries,
+  `Retry-After` support, response validation, request limits, and redacted
+  diagnostics.
+- Added `classify`, `score`, `check`, `verify`, and deterministic `gate` MCP
+  tools while keeping the raw `evaluate` tool compatible.
+- Added a package entry point, `doctor`, standalone JSON evaluation mode, CI,
+  release metadata, and an expanded test suite.
+
+## 0.1.0
+
+- Initial dependency-free stdio MCP bridge exposing `evaluate`.

arbitype-0.6.0/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing
+
+Small, reviewable pull requests are welcome.
+
+Before opening a pull request, run:
+
+```bash
+python3 -m pip install "ruff>=0.8,<1"
+python3 -m ruff check arbitype typesafe_mcp typesafe_codex_mcp server.py smoke_test.py scripts tests
+python3 -m unittest discover -s tests -v
+python3 -m compileall -q .
+python3 -m pip wheel --no-deps . --wheel-dir /tmp/arbitype-dist
+make release-check
+```
+
+`arbitype/` is the canonical implementation package. The `typesafe_mcp/` and
+`typesafe_codex_mcp/` directories are compatibility shims; do not add new
+implementation code there.
+
+The old `typesafe-mcp` PyPI project is deliberately not published as a
+same-name migration wheel: pip ownership tests showed that such a wheel can
+leave legacy console scripts stale. Keep the explicit uninstall-then-install
+migration documented in `docs/REGISTRY_MIGRATION.md`.
+
+Do not add API keys, live request payloads, or provider responses containing
+private data to fixtures. Prefer local HTTP fakes and deterministic tests. New
+tools should preserve the raw `evaluate` escape hatch, document whether their
+decision is advisory, and fail closed when a provider response is malformed.

arbitype-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arbitype contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

arbitype-0.6.0/MANIFEST.in

@@ -0,0 +1,13 @@
+include README.md LICENSE SECURITY.md CHANGELOG.md BENCHMARK.md TESTING.md CONTRIBUTING.md .env.example server.py smoke_test.py
+include server.json
+include scripts/official_sdk_smoke.py
+include scripts/release_readiness.py
+include scripts/validate_registry_metadata.py
+include docs/REGISTRY_MIGRATION.md
+recursive-include arbitype *.py
+recursive-include typesafe_mcp *.py
+recursive-include typesafe_codex_mcp *.py
+recursive-include tests *.py
+global-exclude *.py[cod]
+prune __pycache__
+prune */__pycache__

arbitype-0.6.0/PKG-INFO

@@ -0,0 +1,360 @@
+Metadata-Version: 2.4
+Name: arbitype
+Version: 0.6.0
+Summary: Typed decision tools for AI agents, powered by TypeSafe Jev
+Home-page: https://github.com/Renwang-Huang/arbitype
+Author: Arbitype contributors
+Author-email: renwang-huang@users.noreply.github.com
+License: MIT
+Project-URL: Homepage, https://github.com/Renwang-Huang/arbitype
+Project-URL: Repository, https://github.com/Renwang-Huang/arbitype
+Project-URL: Issues, https://github.com/Renwang-Huang/arbitype/issues
+Project-URL: Changelog, https://github.com/Renwang-Huang/arbitype/blob/main/CHANGELOG.md
+Keywords: arbitype,mcp,model-context-protocol,ai-agents,agent,decision,typed-decisions,classification,routing,verification,guardrails,jev,typesafe-ai,python
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author-email
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+<div align="center">
+
+# Arbitype
+
+<p><strong>Typed decision tools for AI agents.</strong></p>
+
+<p>Classify · Score · Verify · Gate · Route · Review</p>
+
+<p><strong>MCP-native · Powered by TypeSafe Jev</strong></p>
+
+<p>
+  <a href="https://github.com/Renwang-Huang/arbitype/actions/workflows/ci.yml"><img src="https://github.com/Renwang-Huang/arbitype/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/Renwang-Huang/arbitype/releases"><img src="https://img.shields.io/github/v/release/Renwang-Huang/arbitype?display_name=tag&sort=semver" alt="Latest release"></a>
+  <a href="https://pypi.org/project/arbitype/"><img src="https://img.shields.io/badge/PyPI-0.6.0%20pending-lightgrey" alt="Arbitype PyPI publication pending"></a>
+  <a href="https://github.com/Renwang-Huang/arbitype/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Renwang-Huang/arbitype" alt="MIT license"></a>
+  <img src="https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white" alt="Python 3.10 or newer">
+  <a href="https://github.com/modelcontextprotocol/modelcontextprotocol/tree/main/docs/specification/2026-07-28"><img src="https://img.shields.io/badge/MCP-2026--07--28-6F42C1" alt="MCP 2026-07-28"></a>
+</p>
+
+<p>
+  <a href="https://registry.modelcontextprotocol.io/?q=io.github.Renwang-Huang%2Farbitype"><img src="https://img.shields.io/badge/MCP%20Registry-0.6.0%20pending-lightgrey" alt="Arbitype MCP Registry publication pending"></a>
+  <a href="https://glama.ai/mcp/servers/Renwang-Huang/arbitype"><img src="https://img.shields.io/badge/Glama-crawl%20pending-lightgrey" alt="Arbitype Glama crawl pending"></a>
+</p>
+
+<p>
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#why-arbitype">Why Arbitype?</a> ·
+  <a href="#tools">Tools</a> ·
+  <a href="#host-setup">Host setup</a> ·
+  <a href="#configuration">Configuration</a> ·
+  <a href="BENCHMARK.md">Engineering benchmark</a>
+</p>
+
+</div>
+
+Arbitype is an MCP-native typed decision layer for AI agents, powered by
+[TypeSafe Jev](https://typesafe.ai). It turns probabilistic judgments into
+structured decision primitives that an agent or program can consume directly.
+
+> [!NOTE]
+> Arbitype is an independent open-source project. It is not an official
+> TypeSafe AI product or an official integration for any particular agent host.
+
+<!-- mcp-name: io.github.Renwang-Huang/arbitype -->
+
+## Quick start
+
+The shortest path is a local STDIO server launched by `uvx`:
+
+```bash
+export TYPESAFE_API_KEY="your-key"
+uvx arbitype
+```
+
+The API key stays in the process environment. It is not an MCP argument and
+is never printed to standard output.
+
+Install a pinned release with:
+
+```bash
+uvx --from 'arbitype==0.6.0' arbitype
+```
+
+Or run the repository checkout:
+
+```bash
+git clone https://github.com/Renwang-Huang/arbitype.git
+cd arbitype
+export TYPESAFE_API_KEY="your-key"
+python3 server.py
+```
+
+## Why Arbitype?
+
+Generative models are excellent at prose, code, and open-ended generation.
+Agent workflows also need bounded decisions that software can branch on:
+
+```text
+free-form state
+      ↓
+  TypeSafe Jev
+      ↓
+probabilistic judgment
+      ↓
+    Arbitype
+      ↓
+typed decision + probability
+      ↓
+agent / code branch
+```
+
+Arbitype provides that decision layer over MCP. It exposes short, host-neutral
+primitives for classification, scoring, verification, routing, review, and
+fail-closed gate signals. The result is structured data, not a paragraph that
+an agent must interpret again.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    host["AI Agent / MCP Host<br/>Codex · Claude · Cursor · VS Code"]
+    arbitype["Arbitype<br/>Typed decision tools"]
+    jev["TypeSafe Jev<br/>System One Model"]
+    env["TYPESAFE_API_KEY<br/>process environment"]
+
+    host -->|MCP| arbitype
+    arbitype -->|validated HTTPS| jev
+    jev -->|typed probabilistic judgment| arbitype
+    arbitype -->|structured decision| host
+    env -. credential .-> arbitype
+```
+
+The public product is Arbitype; TypeSafe Jev is the current provider. Provider
+configuration intentionally keeps the `TYPESAFE_*` names because the
+credential and endpoint belong to TypeSafe.
+
+## Tools
+
+Arbitype advertises nine read-only, idempotent MCP tools:
+
+| Tool | Input shape | Output |
+| --- | --- | --- |
+| `evaluate` | `state` + TypeSafe `questions` map | Raw typed Jev response |
+| `classify` | `state` + `instructions` + `labels` | Choice and probability distribution |
+| `score` | `state` + `instructions` + ordered `levels` | Weighted score and distribution |
+| `check` | `state` + yes/no criteria | Noul probability |
+| `verify` | `state` + `claims` map | Noul answer per claim |
+| `gate` | `state` + `checks` + thresholds | `pass`, `review`, or `fail` signal |
+| `route` | `state` + `actions` map | One suggested next action; no execution |
+| `review` | `state` + `checks` + thresholds | Review decision and evidence |
+| `health` | Optional `live` boolean | Local configuration; live request only when explicit |
+
+For raw Noul questions, provide non-empty `instructions` or at least one
+non-empty `true`/`false` criterion. Score levels must be non-null structured
+values. These provider-level constraints are validated locally before a paid
+request.
+
+Probabilities and confidence are model signals, not proof. `gate` and `review`
+are advisory decision transformations, not authorization systems, security
+boundaries, or approval engines.
+
+## Host setup
+
+Arbitype uses standard MCP STDIO. For a host that accepts an installed command:
+
+```toml
+[mcp_servers.arbitype]
+command = "arbitype"
+env_vars = ["TYPESAFE_API_KEY"]
+startup_timeout_sec = 10
+tool_timeout_sec = 60
+default_tools_approval_mode = "prompt"
+```
+
+For a checkout:
+
+```toml
+[mcp_servers.arbitype]
+command = "python3"
+args = ["/absolute/path/to/arbitype/server.py"]
+env_vars = ["TYPESAFE_API_KEY"]
+startup_timeout_sec = 10
+tool_timeout_sec = 60
+```
+
+The same process can be registered by Claude, Cursor, VS Code, Codex, or any
+other MCP host using its native configuration format. Keep the key out of host
+configuration files; use the host's environment forwarding mechanism.
+
+## CLI and Python
+
+The canonical CLI and package are `arbitype`:
+
+```bash
+arbitype --version
+arbitype doctor --json
+cat request.json | arbitype evaluate
+arbitype evaluate --input request.json
+```
+
+The Python API is intentionally small:
+
+```python
+from arbitype import TypeSafeClient
+
+client = TypeSafeClient()
+result = client.evaluate({
+    "state": "A payment failed twice.",
+    "questions": {
+        "urgent": {
+            "type": "noul",
+            "instructions": "Does this require urgent handling?",
+        }
+    },
+})
+```
+
+### Package and import compatibility
+
+The canonical wheel contains the one implementation plus the legacy import
+shims. The old PyPI project is not deleted, yanked, or released under a new
+identity.
+
+| Surface | Name | Status |
+| --- | --- | --- |
+| PyPI | `arbitype` | Canonical distribution |
+| Python | `arbitype` | Canonical import |
+| Python | `typesafe_mcp` | Legacy compatibility shim |
+| Python | `typesafe_codex_mcp` | Legacy compatibility shim |
+
+### CLI compatibility
+
+| Command | Status |
+| --- | --- |
+| `arbitype` | Canonical CLI |
+| `typesafe-mcp` | Legacy CLI alias |
+| `typesafe-codex-mcp` | Legacy CLI alias |
+
+### Tool compatibility
+
+| Tool | Status |
+| --- | --- |
+| `route` | Canonical |
+| `review` | Canonical |
+| `codex_route` | Legacy alias |
+| `codex_review` | Legacy alias |
+
+The historical `typesafe-mcp` PyPI project remains intact. A metadata-only
+replacement with the same distribution name was tested and rejected because
+pip can remove legacy console-script files while replacing the old
+distribution. Therefore no `typesafe-mcp==0.6.0` migration package will be
+published.
+
+Existing users should use this explicit, safe migration:
+
+```bash
+python -m pip uninstall typesafe-mcp
+python -m pip install arbitype
+```
+
+New installations should use `arbitype` directly. This leaves one
+distribution owning the canonical implementation, compatibility shims, and
+all three CLI entry points.
+
+## Discovery and Registry
+
+The canonical MCP Registry identity is:
+
+```text
+io.github.Renwang-Huang/arbitype
+```
+
+The intended package entry is:
+
+```text
+uvx arbitype
+```
+
+The PyPI, MCP Registry, and Glama links are prepared before publication, but
+their badges remain explicitly marked pending until the external listings are
+verified. Release ordering and the legacy Registry migration procedure are
+documented in [docs/REGISTRY_MIGRATION.md](docs/REGISTRY_MIGRATION.md).
+
+The former identity `io.github.Renwang-Huang/typesafe-mcp` is a legacy
+identity. It must remain available for existing users and should be marked
+deprecated through the Registry publisher when that mutation is supported.
+New installations should use the Arbitype identity.
+
+## Configuration
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `TYPESAFE_API_KEY` | — | Required TypeSafe bearer credential |
+| `TYPESAFE_BASE_URL` | `https://api.typesafe.ai` | API base URL |
+| `TYPESAFE_MODEL` | `jev-latest` | Model alias; legacy name supported |
+| `TYPESAFE_DEFAULT_MODEL` | `jev-latest` | Official SDK-compatible model name |
+| `TYPESAFE_TIMEOUT_SECONDS` | `10` | Per HTTP attempt timeout |
+| `TYPESAFE_MAX_RETRIES` | `2` | Retries after the initial request |
+| `TYPESAFE_RETRY_BACKOFF_SECONDS` | `0.5` | Initial exponential backoff |
+| `TYPESAFE_MAX_STATE_CHARS` | `120000` | Serialized state limit |
+| `TYPESAFE_MAX_QUESTION_CHARS` | `60000` | Serialized question limit |
+| `TYPESAFE_MAX_REQUEST_BYTES` | `512000` | Whole request limit |
+| `TYPESAFE_MAX_RESPONSE_BYTES` | `4194304` | Provider response limit |
+
+Custom provider endpoints must use HTTPS. Plain HTTP is accepted only for
+loopback hosts such as `localhost`, `127.0.0.1`, and `::1`. Redirects are
+disabled so a bearer credential is never forwarded to a redirect target.
+
+## Security boundaries
+
+Arbitype is a local MCP adapter and typed decision layer. It is not:
+
+- a sandbox for untrusted code;
+- an authorization or identity system;
+- a prompt-injection firewall;
+- a security approval boundary; or
+- an official TypeSafe AI product.
+
+It does not execute actions suggested by `route`, edit files, run shell
+commands, or treat model probabilities as proof. Read [SECURITY.md](SECURITY.md)
+before using live credentials.
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests -v
+python3 -m compileall -q .
+python3 -m pip wheel --no-deps . --wheel-dir /tmp/arbitype-dist
+```
+
+The test suite uses local fakes and does not need an API key. The official MCP
+Python SDK interoperability smoke test is in
+[`scripts/official_sdk_smoke.py`](scripts/official_sdk_smoke.py). A live Jev
+check is opt-in and paid:
+
+```bash
+TYPESAFE_API_KEY="your-key" arbitype doctor --live
+```
+
+See [TESTING.md](TESTING.md), [CONTRIBUTING.md](CONTRIBUTING.md), and
+[BENCHMARK.md](BENCHMARK.md) for the full engineering checks and comparison.
+Maintainer migration details are in
+[`docs/REGISTRY_MIGRATION.md`](docs/REGISTRY_MIGRATION.md).
+
+## Release identity
+
+Arbitype is currently released as `0.6.0` because it remains Beta while its
+canonical public identity moves to the new package, CLI, and Registry name.
+The old package history remains intact; the brand migration does not rewrite
+Git history or delete the former PyPI project.