Repository navigation
rutis 0.22.0
0.22.0 was released on 2026-11-17. The GitHub Release exists with the five platforms' rutis-host binaries and their sha256 files; crates.io, npm, PyPI, Maven and the Go module have 0.22.0. The gate's CI dry run (run 44086850364) passed, and the release run for tag v0.22.0 ran the same gate. These notes cover only what is merged; "After the release" at the end lists what is still undone: the two-machine network smoke and the post-release agent trial.
0.22 folds 0.23's formal coverage into this release: the session protocol has a current specification, 1368 rules are in the rule tracker, the 7 TLA+ model directories (17 modules, 220 configurations) and the 63 shuttle models of four crates (27 in the kernel, 30 in rutis-bridge, 3 in rutis-host, 3 in rutis-loader; the last six run in no workflow) were reconciled and filled in for 0.22; event-listener close admission now publishes a permanent marker when a subtree closes, and Entry::live no longer walks the ancestor chain on every call. No API a plugin sees is removed or renamed, and the wire format is unchanged. On the behaviour side it fixes a set of close, withdrawal, heartbeat and unknown-field edges. Read migrating to 0.22 before upgrading.
What is in this release
| Work | Issue | What this release has |
|---|---|---|
| Event close admission | #1025 (closed) | A permanent FiberInner::lineage_closed marker; non-root and root shutdown both write the marker for the fixed subtree under Shared.admission before publishing the existing closing; Entry::live reads the owner marker only. 7 deterministic race tests, 1 shuttle model, 7 configurations in specs/event-close. On the reference machine (32-core Linux x86-64), 1000 instances take 14.87 s to create and 10.32 s to close; CI's cpu job (run 42932771727) takes 33.17 s to create on a GitHub runner, recorded as a runner number only, not a hard threshold. ECA-7 (the race between registration and the marker pass) is still unverified. |
| Session protocol specification and unknown fields | #635 (closed) | The first version of docs/protocol-session.en.md, 82 SESS-* rules: frames, handshake, calls, references, cancellation, malformed frames, size limits, unknown fields. The unknown-field rule is "reject, but fail only that call": invoke/call/get/await answer bad-frame, return/throw fail only the waiting call, hello fails the handshake, and release/cancel ignore it; all seven runtimes agree. The shared malformed-frame matrix has 25 cases (13 single-frame, 12 multi-frame/sequence). |
| Rule tracker | #634 (closed) | 1825 rows: 219 register rows, 54 handwritten rows (TRC 44, ECA 10), 1552 protocol rows (1368 current plus 184 superseded). The 1368 current protocol rules were re-extracted against the 0.22 sources: 179 verified, 364 partly verified, 479 unverified, 42 explicitly not guaranteed, 103 withdrawn, 201 not counted separately; the 184 superseded rows in the issue snapshot were not re-checked. 67 rows were raised to verified with evidence and a mutation check (35 in the 2026-11-17 batch, 32 after it). The 219 register rows and the 10 handwritten ECA rows have not been re-extracted row by row. |
| Protocol models | #613 (closed) | 7 TLA+ model directories, 17 modules, 220 configurations: cross-runtime-sync, remote-lease, row-lifecycle, event-close, events (four modules), peer-rows, call-lifecycle; every configuration has an expected.txt, and CI's specs job runs them all. Implementation problems the models found and that are fixed include the link old-generation reinsertion, the Kotlin app start/stop race and the Node/Bun force-kill timeout; #1101 and #1102 are fixed and #1100 is settled. |
| Kernel concurrency, trace and conformance | #622, #624, #639 (all closed) | 27 kernel shuttle models and 30 in rutis-bridge, each run 1,000,000 iterations every night by stress.yml; the 6 models in rutis-host and rutis-loader run in no workflow; 7 deterministic race tests. The trace validator has 23 cases (channel/frames, reference counts, the error graph, call scope, limits, replace/reconnect classification), and the lease suite gained Go and Bun columns; the wait-graph trace is checked against CrossRuntimeSync.tla. Every one of the 161 rules in #639 now has a conformance or ordinary test, or a written reason it was withdrawn; the last real defect found was #1171, fixed by #1173. |
| Non-Rust scheduling, properties and fuzzing | #630, #631 (closed) | Controllable scheduling with the Node frame pump and Python's SteppedLoop; 6 grant-rollback properties, 5 value/frame/bad-frame properties, the listener-table model property; 4 cargo-fuzz targets actually run with no crash; Miri ran 30 fixed inputs. Kani's 6 harnesses do not converge in 90 minutes on this machine, so there is no conclusion and it is not written as passing. |
Behaviour changes
| Where | Before | Now |
|---|---|---|
An accepted emit dispatch meets cancel |
cancel removed it from the queue and no listener ran |
It dispatches as usual; the caller has given the call up, so it discards the late reply, and the session is unaffected (#1121, #1129) |
| The host calls a listener the runtime has just withdrawn itself | Node and Bun threw BindingError: listener <id> of <name> is withdrawn; the other runtimes failed once |
The call answers with no result (each language's own empty value); waterfall calls next and returns its value. An unknown id, and a row the host itself withdrew, still answer listener <id> of <name> is withdrawn (#1135, #1138, #1137, #1189) |
ctx.provide after a row starts unloading |
Python and Bun accepted it; the service stayed in the table with no row, and Python announced it to the host if the unload had not finished | Refused as in Rust, Go, Kotlin and Swift: Python RuntimeError: row <row> is not active, Bun Error: row <row> is not active; no withdrawal is registered and no service frame is sent (#1143, #1149, #1189) |
| When a listening side's heartbeat starts | At accept or connection construction; a slow old-lease cleanup closed the new connection with 1001 before hello | After hello is sent successfully; Go, Swift, Node, Bun and Kotlin agree, so a slow cleanup no longer closes the new connection by mistake (#1102, #1182, #1181, #1183) |
| Kotlin and Swift receive a frame with an unknown field | Ignored silently | Refused for that call: unknown field "x" in invoke, code is bad-frame, data is {op, fields}; hello fails the handshake (incompatible session: unknown field "x" in hello); release/cancel still ignore it (#635, #1156) |
filter(predicate) returns a Promise / thenable / coroutine |
Truthy, so every listener passed | The dispatch fails: Node and Bun TypeError: a filter predicate must answer with a boolean, not a Promise; Python TypeError: a filter predicate must return a boolean, not an awaitable, and the coroutine is closed first (#637, #1156) |
A received reference's origin entry is not <endpoint>:<n> or s<n>/<endpoint>:<n> |
Rust treated it as an ordinary call id | The session ends with invalid reference, as in Node, Python and Go (#637, #1156) |
An isolate label contains U+0001 |
Accepted; it shared a namespace with the labels the loader makes for row-leased services | The configuration is refused: isolate.<name> of "<id>" must not contain U+0001: it is reserved for the loader's row labels (#637, #1156) |
A node-imported service announcement services.announce |
row was null, so the importing side did not know the provider's row |
It carries the provider's row id; it is absent when there is no row. An old peer ignores the optional field; a new peer reading an old announcement gets None (#1171, #1173) |
The host receives a row's rows.unload before the same key's rows.load |
The later load mounted the row and left an orphan with no unload | The later load is refused: <key> was unloaded. The tombstone is per session; unloading a mounted row leaves none, so the same key loads in a new session (#1101, #1185) |
| Node and Bun decide whether a synchronous wait is a cycle | A synchronous call whose reply had been read still counted in the wait chain, so SyncWaitCycle was occasionally reported by mistake |
Only unanswered synchronous calls count; a real cycle is still refused (#639, #1178) |
| The failure this end reads when the far end rejects with 4003 | peer disconnected (transport) |
endpoint mismatch: <reason>; both directions of a channel pair now get the same close reason (#1130) |
Other fixes:
- Python's first import of a plugin: on Windows, when the directory mtime fell on the same tick, a new file could be missing from
FileFinder's cached listing and the import failed withModuleNotFoundError. The firstimport_modulenow callsimportlib.invalidate_caches()first; the reload path is unchanged (#1139, #1140). - Kotlin app hosting and Node/Bun force-kill: after
stop()returns, the app no longer dials or binds; a takeover kills the old runtime afterRUTIS_SHUTDOWN_TIMEOUT + 2s, not a hard-coded 5 seconds (#1096). - Go reading a token line on Windows:
bufioswallowed the greeting that followed it, so every test-tool case reportedpeer disconnected; it now reads to the end of the line byte by byte and leaves the greeting for the next read (#1087). - Late entries after a provider is withdrawn: once an
eventsprovider is withdrawn, an entry registered in the window is no longer inserted back into the table (#1096).
Verification and models
- Current specification:
docs/protocol-session.en.mdhas 82SESS-*rules. The shared malformed-frame matrix has 25 cases, with an entry point in Rust, Node, Bun, Python, Go, Swift and Kotlin. Swift's cases compile on macOS only and run in CI'sruntimes-swiftjob. - Rule tracker: 1825 rows (219 register, 54 handwritten, 1552 protocol). The 1368 current protocol rules were re-extracted against the 0.22 sources, with the statuses above; 67 rows were raised from
未验证/部分验证to已验证with evidence and a mutation check.node tools/formal-trace.mjsreports 0 problems, and the tracker check runs in CI. The 219 register rows and the 10 handwrittenECArows have not been re-extracted row by row (theTRC44 rows and all six protocol partitions have). - TLA+: 7 directories, 17 modules, 220 configurations, each with an
expected.txt; inevent-close's 7 configurations, 4 mutations violateClosingImpliesMarked,CommittedStaysOut(twice) andCleanupOnce, so the model is not vacuous. CI'sspecsjob runs every configuration of every model on PRs that changespecs/**and in the nightly full run. - Shuttle: 27 kernel models and 30 in
rutis-bridge, each run 1,000,000 iterations every night bystress.yml, and a failure prints a schedule that can be replayed; the 6 models inrutis-hostandrutis-loaderrun in no workflow; when#1025's marker publish order is written wrong, the model fails immediately withthis node is closing while its lineage marker is clear. - Trace and conformance: the channel/frame validator has 23 cases; the wait-graph trace records the six operations in
waits.rsand replays them againstRustSucc, and breaking the same log must be reported. The lease suite has Python, Go and Bun columns;sync_cycleslacks Kotlin andhost_gonelacks Swift and Kotlin (Swift plugins build on macOS only, and Kotlin needs JDK 17 plus:rutis-conformance:fatJar). - Properties, fuzzing, Miri, Kani: 6 grant-rollback properties, 5 value/frame/bad-frame properties, and the listener-table model property; 4 fuzz targets actually run with no crash; Miri ran 30 fixed inputs (13 frames, one over-deep nesting, 9 framing seeds, 7 error graphs) with no UB. Kani's 6 harnesses do not converge, so there is no conclusion and it is not written as passing.
- Release-check numbers:
node tools/check-guarantees.mjsreports 219 rows and 1232 markers with 0 problems; the register's 40 core commitments have 0 unverified (33 verified, 7 partly verified); the tracker has one more unverified core commitment,ECA-7, outside the register.
Explicitly not guaranteed
- The trust boundary is not in this release (#1040): a runtime row can announce any service name host-wide, and the host has no per-row policy to confine or reject it. 0.22 adds no
rutis.jsonfield, global allowlist, service namespace or dynamic-nameisolate. - Delivery after a subtree closes: the design's "
Ctx::emit()itself does not fail only because a subtree closed, and does not reach that subtree's live listeners" is still a proposal; the existing service-after-stop test explicitly leaves delivery after a stop uncommitted (crates/rutis/src/events/api.rs:453-480,crates/rutis/tests/service_emits.rs:70-83). This release fixes only "no new listener call starts after the commit, and accepted calls drain". - Replies after a cancel:
SESS-61is still explicitly not guaranteed and the implementations have not agreed. Rust does not reply to a queued call or anawait; it does run an acceptedemitdispatch and leaves the reply for the caller to discard; other languages decide by method and signal. Cancel-table cleanup and the cancel-reply rule are #1099. - Unknown fields are not an extension mechanism:
SESS-69does not guarantee that a new optional field whose meaning does not change arrives silently at an old receiver; an old implementation fails that call underSESS-66. A new frame or a changed meaning needs a protocol version bump; a new capability is used only when declared. - The implementation-level close-admission rules:
ECA-7(the race between registration and the marker pass) is unverified; dedicated cases for aLoadingowner,oncenot being consumed, remote entries and multi-generation reloads are still missing. Rules 3, 6, 7, 8 and 9 in design §3 still read "proposal, not verified". - Formal coverage is not complete yet: 479 current protocol rules in the tracker are unverified and 364 are only partly verified; #776 and the remaining #1270–#1274 are still open, while #613, #622, #624, #630, #631, #634 and #635 are closed. Kani has no conclusion (#1271 has to split the validation predicates and the const ABI out first); the Swift/Kotlin trace columns are not done (the Swift column for
host_goneandlease_e2eis #1272); the session layer, event host, runtime supervision and host reload have shuttle models now: the 30 inrutis-bridgecover sessions, the event host, channels, subprocesses and more, the 6 inrutis-hostandrutis-loadercover runtime supervision, host reloads and a binary runtime's restart, and those 6 run in no workflow; dylib has none; theinterleave.rsreference model is merged (#1190). - Still-open protocol and implementation gaps: the protocol signal for an asynchronous call that is sent and forgotten versus one awaited later (#1098), cancel-table cleanup and the reply after a cancel (#1099), and the wait-graph blind spot under a single host worker (#1103). The further performance work in #1125 does not block 0.22.
What developers see
| Role | What they see |
|---|---|
| Plugin authors | No new plugin API. To change: a filter predicate answers synchronously; do not call ctx.provide after a row starts unloading; do not treat unknown fields on Kotlin or Swift as an extension. A listener you withdrew yourself answering with no result is a loosening and needs no change. Heartbeats, a service's row, SyncWaitCycle, Python imports and Kotlin app hosting need no change. |
| Host owners and deployers | No new configuration, rutis.json field or protocol version: session protocol 4, format 1, plugin API 3. The texts and fields that change: a 4003 rejection is endpoint mismatch: <reason>; a node-imported rutis/service event's row is the provider's row id; an unload that overtakes its load gets <key> was unloaded. An old runtime package keeps its old behaviour, and the session still comes up. |
| Rust host authors | No kernel public API is removed or renamed, and crates/rutis/public-api.txt is unchanged; rutis-bridge only gains tracing and test-support types and functions. Close admission is an internal marker and changes neither the shutdown result nor the event protocol. InactiveEffect is still fiber disposed. |
| Runtime authors and contributors | The current session specification is docs/protocol-session.en.md; unknown fields, the malformed-frame matrix, the heartbeat start, the withdrawal race, the provide refusal and a service's row follow it. The tracker, TLA+ models, shuttle, trace and conformance suites are contributor evidence, not runtime output; #613, #622, #624, #630, #631, #634, #635 and #639 are all closed, and the remaining #1270–#1274 and #776 are still open. |
Compatibility
- The session protocol is still 4 (
ENDPOINT_PROTOCOLincrates/rutis-bridge/src/session/mod.rs),rutis.json'sformatis still 1, and the plugin API is still 3; no capability or handshake requirement is added, and no required field is added to a wire frame. - Old and new versions mix: an old runtime package keeps the old behaviour on its side (old Kotlin/Swift still ignore unknown fields, for example), and the session still comes up.
services.announce'srowis optional: an old peer ignores it, and a new peer reading an old announcement getsNone. - No public Rust API is removed or renamed; the kernel's public API snapshot
crates/rutis/public-api.txtis unchanged.rutis-bridgeonly gains tracing and test-support types and functions; nothing is removed or renamed. - A dylib plugin is rebuilt with 0.22.0's SDK, as with every release.
rutis.jsonand the dsh user layer have no format change: the persisted sample is intests/fixtures/persisted/0.22.0/, copied from 0.21.0, and the expectations do not change;cargo test -p rutis-host --test persistedandcargo test -p rutis-dsh --test persistedpass. The rest of the gate's results are in the next section.
Upgrading
Most plugins and hosts need no code change. Three behaviour changes can be met: filter(predicate) must answer synchronously; ctx.provide must not be called after a row starts unloading; and a listener you withdrew yourself no longer fails with withdrawn, it answers with no result. Kotlin and Swift also no longer ignore unknown fields, and an isolate label must not contain U+0001. See migrating to 0.22 for each change.
After the release
- Version numbers: every package, the version numbers in the guides and the Swift package version in
READMEare at 0.22.0 (node scripts/train.mjsprints0.22.0). The workspace declaration inCargo.tomlis still0.6.0, as it was for the 0.21.0 release: decide and record the package/version process as the roadmap §3 says before changing it. - Release gate: the whole gate passed as a CI dry run (2026-11-17,
gh workflow run release.yml --ref main -f dry-run=true, run 44086850364): of its 70 jobs 59 succeeded and 11, which only run when publishing, were skipped (the registry publishes, the GitHub release, the checks after publishing and the report); the five platforms (linux-x64, linux-arm64, darwin-x64, darwin-arm64, win32-x64) all packaged and installed, the Windows dylib tests ran on GitHub'swindows-2025, and the macOS Swift cases and the rest of the macOS jobs ran on the self-hosted macOS runner (macos-1, labelrutis-release;install / planlanded onmacos-2). On the first attempt onlynetwork-macosfailed, indev_follows_a_python_project(crates/rutis-host/tests/dev.rs:467); the summarisingci-okjob failed with it, and the same commit passed on a rerun. The cause is not known. The parts a local machine can run (2026-11-17, Linux x86-64) also pass: the train's 10 crates package and verify withcargo package;tools/install/local-artifacts.shbuilds the five npm packages, the two wheels and the release binary (its sha256 checks out);cargo test -p rutis-e2e --test install -- --ignoredpasses its npm, PyPI and release-binary scenarios;cargo semver-checksagainst 0.21.0 finds no breaking change (with--release-type minor, three crates run 202 lints each and pass them all);tools/public-api.shleaves the snapshot unchanged under the nightly CI pins (nightly-2026-10-16). Each result and its command are in the "0.22.0" section of the release guide. - Network smoke and agent trial: the network smoke ran on loopback only; the two-machine half and the outage did not; the pre-release agent trial (#663) has not run.
- Issues still open: #776 and the remaining #1270–#1274; #613, #622, #624, #630, #631, #634, #635, #639 and #1025 are closed. #1040 stays postponed.
- Statistics: the tracker numbers here are from the current
node tools/formal-trace.mjsoutput (1825 rows; protocol re-check 179/364/479/42/103/201, plus 184 superseded), andnode tools/check-guarantees.mjsprints 219 rows and 1232 markers. The same numbers indocs/quality-status.en.mdanddocs/quality-status.mdand indocs/formal-trace/README.en.mdandREADME.mdwere synced to this re-check.