feat(protocol): adopt lanok-core for errors, classification, and version negotiation

[chaliy]

What changed

Deletes mira's hand-rolled copies of three things the yolop extension protocol also maintains.

204 lines removed, 99 added. Draft, because it cannot merge yet (see Blockers).

Removed from mira	Replaced by	Lines
RpcError + codes	lanok_core::RpcError, re-exported	83
enum Inbound + fn classify	lanok_core::Message	47
version_major / version_compatible	lanok_core::Negotiation	12

protocol.rs loses 84 lines, host.rs loses 100.

Is it drop-in? Measured, not asserted

The question worth answering is not "does it still work" but "are the bytes the
same". Measured by building the same wire_probe example against origin/main
in a worktree and against this branch, and diffing the emitted lines:

message	main	this branch	identical
request	{"jsonrpc":"2.0","id":1,"method":"run","params":{...}}	same	yes
notification	{"jsonrpc":"2.0","method":"progress","params":{...}}	same	yes
ok response	{"jsonrpc":"2.0","id":1,"result":{...}}	same	yes
error response	{"jsonrpc":"2.0","id":1,"error":{...}}	same	yes
retryable error	{"code":-32603,"message":"busy","retryable":true}	same	yes
plain error	{"code":-32603,"message":"boom","retryable":false}	{"code":-32603,"message":"boom"}	no
coded error	{"code":-32602,"message":"bad","retryable":false}	{"code":-32602,"message":"bad"}	no

Six of seven byte-identical. One difference: retryable is omitted when
false instead of written as false.

That difference sits inside mira's own forward-compatibility contract, and the
proof is that the readers already existed before this PR:

• mira's published schema lists only message as required; retryable carries
  "default": false, restored explicitly so the artifact still says so.
• the Python SDK declares retryable: bool = False.
• the TypeScript SDK declares retryable?: boolean.
• both polyglot example studies drive the adopted host green unmodified.

So: functionally drop-in, and byte-identical except for one field whose absence
every existing reader already reads as false. Both shapes are now pinned by
tests in this repo and in lanok, so neither can drift again unnoticed.

Why

lanok is the extraction of the plumbing mira and yolop each wrote separately. yolop's crates/yolop-yep/src/protocol.rs opens with "Conventions (from the mira eval protocol)", and its server SDK says it "mirrors the mira SDK's serve() design". Both grew the same field-based classification, the same MAJOR.MINOR rule, the same JSON-RPC-shaped error.

The classification rule is the one worth sharing. mira's own comment calls it the safety property:

a reverse request's id lives in the study's own id space and would otherwise collide with the host's pending ids (both start at 1), spuriously completing an unrelated in-flight request with an "empty response"

That is a subtle, load-bearing invariant. Having one implementation of it, tested once, is the point of the kit.

It fixes a bug on the way

MIN_PROTOCOL_VERSION has always been published in meta.json and never checked. version_compatible compared majors only, so a study announcing a version this build had dropped support for connected anyway and failed later at whichever method it could not satisfy. Today the constant equals the major floor so nothing is observably broken; the moment mira raises it, it was silently ignored. A malformed version is now refused instead of parsing as major 0.

Adopting it required fixing lanok, not mira

This is the part worth reading, because it is what a real adoption surfaces and a design document cannot.

1. retryable was in the wrong place. lanok buried it inside data, on the argument that JSON-RPC enumerates the members of an error object. The spec says code and message are required and data is optional; it does not forbid more. Both protocols lanok exists to serve already had the flag at the top level, in their Rust types and in mira's Python and TypeScript SDKs. The strict reading bought nothing and would have broken every existing study. Fixed in lanok@814f482.

2. serde_json/preserve_order leaked. Taking the dependency reordered the keys of every committed schema artifact mira generates: 1159 lines of diff, content identical. Cargo unifies features across the whole graph, so lanok-core was changing how mira serialises JSON. Fixed in lanok@d2ce390 and generalised into lanok's architecture concept.

3. Missing with_code, and thinner field docs than mira's. The schema artifacts a protocol publishes carry those doc comments, so adopting lanok would have replaced better prose with worse. Ported mira's upstream instead.

4. Cancellation was a setting, not a hook, and the handshake was lanok's to name. Both surfaced when this PR tried to take the next step (below). Fixed in lanok@3e865ed and lanok@d824c12: a protocol now supplies an abandon hook and its own handshake method names, rather than choosing among knobs lanok guessed at.

The pattern across all four: lanok kept deciding things that were not its to decide. Each was found by contact with a real protocol, none by design thinking.

Before / After

// before: min advertised, never enforced
pub fn version_compatible(other: &str) -> bool {
    version_major(other) == version_major(PROTOCOL_VERSION)
}

// after
pub fn version_compatible(other: &str) -> bool {
    match other.parse::<lanok_core::Version>() {
        Ok(peer) => negotiation().accepts(peer).is_ok(),
        Err(_) => false,
    }
}

Gate green: cargo fmt --check, clippy -D warnings --all-features, cargo test --workspace (167 in mira-eval, no failures), --features protocol-unstable, mira-schema-gen --check, and mira run --study examples/greet.rs.

The schema diff is five lines: the same fields with better descriptions, and int32 becoming int64.

Behaviour deltas

Both narrow, both tested:

• A missing code reads as INTERNAL_ERROR rather than 0. That is how an error declining to classify itself should be read, and 0 is not a JSON-RPC code. Retry behaviour keys on retryable and the message, not this value.
• A response with neither result nor error surfaces as a deserialization failure at the typed call site rather than the string "empty response". Still an error, more specific.

What is left

host.rs still carries ~150 lines that lanok_peer::Peer already owns: the pending map, id allocation, the write-under-lock, RequestGuard's cancel-on-drop, and reader_loop's EOF drain. Adopting it would also add two things mira lacks: a connection-end drain that fails pending requests at once rather than per-timeout, and per-request timeouts.

That step was blocked on two lanok gaps, both now closed by the fixes above:
mira's cancel is a request the study acknowledges, not a notification, and it
is armed only for cancelable methods against a study that advertises cancel.
The abandon hook expresses both. study.rs's serve loop is the same story on
the other side. Neither is in this PR, because the peer migration deserves its
own diff.

Risk

• Low. One wire byte changed, in a field every reader already defaults; 167 tests pass; the two behaviour deltas are covered by tests that state their reasoning.
• The dependency is the risk, not the diff. See below.

Blockers

1. lanok is unpublished. The dependency is git + pinned rev, which makes mira unpublishable. It must become a version dependency before the next release. This is why the PR is a draft.
2. lanok is pre-1.0, so its Rust API may still move. Its wire contract is separate and stable by design.

Checklist

• Tests added or updated
• Backward compatibility considered: wire measured field by field above; the one difference and the two behaviour deltas are documented and tested

🤖 Generated with Claude Code

https://claude.ai/code/session_014LYBU1vgSfMU9EjmUCku8z

[chaliy]

CI is red, and I am not fixing it in this PR. The cause is one thing, and it is Blocker 1, not the diff.

All four failing jobs (Lint, Test, Audit, Examples) die in the same place, within ~8 seconds, before compiling anything:

failed to acquire username/password from local configuration

Cargo.toml points lanok-core at https://github.com/everruns/lanok, which is a private repository. GitHub Actions checks out mira with a token scoped to mira, so cargo cannot fetch the dependency. Confirmed: anonymous GET https://github.com/everruns/lanok returns 404.

Nothing in the change is failing. Locally, with access to lanok, the full gate is green: cargo fmt --check, clippy -D warnings --all-features, cargo test --workspace (167 tests in mira-eval), --features protocol-unstable, mira-schema-gen --check, and mira run --study examples/greet.rs.

Two ways to make CI green, both decisions rather than patches:

1. Publish lanok to crates.io and switch to a version dependency. This is the path the PR already names as required before mira's next release, since a git dependency makes mira unpublishable either way. It also clears cargo-deny check sources, which rejects git sources.
2. Give CI a credential for the private repo (the GITHUB_TOKEN already in Doppler, via git config url.insteadOf before cargo runs). Faster, but it puts a cross-repo token into every mira CI job and still leaves the publishability blocker.

I have not done either: option 1 is a release decision and option 2 widens what mira's CI holds. The PR stays a draft until one is chosen.

---

Generated by Claude Code