Adding a language runtime to rutis

rutis (https://github.com/arcships/rutis) has a Rust core; plugins in other languages connect through runtimes. This skill does not depend on the rutis documentation; everything it refers to is in references/:

The key idea: the rutis paradigm (dependency gating, lifecycle, configuration reconciliation) is implemented once, in the Rust core. A runtime and its SDK are a thin leaf layer that only connects one language's plugins. If you find yourself implementing the paradigm again in the new language, you are going the wrong way.

0. Decide whether to do it

Using the criteria in references/principles.md:

• What ecosystem does it bring? A runtime is added for an ecosystem, not to have one more language.
• Is there a concrete user? If not, wait — Go and the desktop Kotlin/JVM runtime were both "when there is a need".
• Does an existing runtime already cover it? (TS plugins already run on Node and Bun.)

1. Design doc first, code second

• In the rutis repository write docs/design-<language>-runtime-<date>.md and .en.md (the Chinese one is authoritative). Structures to follow:
  • a language compiled into programs: https://github.com/arcships/rutis/blob/main/docs/design-go-runtime-2026-10-10.en.md
  • a language that loads packages by name: https://github.com/arcships/rutis/blob/main/docs/design-bun-runtime-2026-10-09.en.md
  • a language with app hosting: https://github.com/arcships/rutis/blob/main/docs/design-swift-sdk-2026-10-12.en.md
• Settle the decision table; leave no "to be decided". Where a default is obvious, take it and state why.
• Include a "departures from the master plan" section. When merging, update the multi-language master plan's milestones and §9 (reentrancy progress).

2. Framework constraints

3. Decisions every runtime must state

4. The runtime contract

All of it is in references/runtime-contract.md. The fastest way to get the behavior right is to read an existing implementation alongside it:

• Python: https://github.com/arcships/rutis/tree/main/python/rutis/rutis (peer.py, runner.py, __main__.py, websocket.py)
• Go: https://github.com/arcships/rutis/tree/main/go/rutis (serve.go, listen.go, runtime.go, plugin.go)
• Bun: https://github.com/arcships/rutis/tree/main/bun/rutis-bun/src

5. What changes in the rutis repository

Compiled from the files Bun (arcships/rutis#200) and Go (arcships/rutis#227) actually changed.

Language side

• <language>/…: session layer, SDK, runtime entry point, host-free test helper (like Go's rutistest, Python's rutis.testing)
• A conformance entry point for the Rust tests to start

rutis-bridge

• src/runtime/process.rs: Launcher::<language> (command, working directory, how the channel is handed over)
• src/runtime/local.rs: LocalRuntime::<language> and the runtime name
• src/runtime/mod.rs; a feature in Cargo.toml
• Tests: tests/runtime_conformance.rs, tests/session_matrix.rs, tests/<language>_runtime.rs; for remote use tests/websocket_conformance.rs (and dial_conformance.rs for dialing out)

rutis-loader

• Load by name: src/runtime.rs (RuntimeResolver). Compiled program: src/runtime/<language>.rs, reusing Go's manifest machinery
• src/lib.rs; a feature in Cargo.toml
• Tests: tests/<language>_rows.rs, tests/multilang_<language>.rs, tests/instance_<language>.rs, tests/leases.rs

rutis-host Every local language is one entry in a registry (arcships/rutis#230): config.rs, host.rs, new.rs, project.rs and main.rs loop over it and need no edit. Read https://github.com/arcships/rutis/tree/main/crates/rutis-host/src/languages first: node.rs (load by name) or go.rs (compiled program).

• src/config.rs: a runtimes.<language> field in Runtimes and its settings type (this is the rutis.json format; the persisted-fixture tests guard it)
• src/languages/<language>.rs: one type implementing the Language trait: its runtimes key; rebase/merge of its settings; the names it takes as runtimes.remote[].language and how its rows are named (rows); runtime, which finds the package or interpreter, runs the preflight check of its version and builds the LocalRuntime (a compiled-program language with one runtime per binary overrides start instead, as Go does); new --lang names, template and next steps; dev: how a project is recognized (is_project, project_file) and the rows that run it (the host never compiles; it only runs the project's own build)
• src/languages/mod.rs: its mod line and its line in LANGUAGES (the order messages list languages in; the host starts them in reverse, so Node, whose resolver takes bare npm names, stays first)
• src/main.rs: only the USAGE help text names the languages. A compiled-program language that rebuilds in dev or lists its binaries in check follows Go there (host.go, project::GoDev)
• templates/<language>/: plugin, tests, rutis.dev.json, publish workflow

Release and CI

• .github/workflows/ci.yml: a runtimes-<language> job; release.yml
• scripts/train.mjs: version file and package coordinates

Documentation (both .md and .en.md)

• docs/guide/<language>-plugin.md; a column in docs/guide/plugin-api.md; docs/guide/rutis-host.md; docs/guide/nodes.md for remote use
• The package table in the READMEs; toolchains in CONTRIBUTING
• The multi-language master plan: milestones and §9

6. Phases (the Go / Swift rhythm)

1. Merge the design doc.
2. Session layer and conformance entry point: pass runtime_conformance.
3. Runtime contract, SDK and Rust wiring: pass <language>_runtime, <language>_rows and the new multilang column; all existing tests stay green.
4. Developer workflow: new, dev, check, template, publishing.
5. Remote: listen: and dial:, passing websocket_conformance and dial_conformance.

7. Common mistakes