net.
moves
at light.

Named after Skid Row's 1991 single — the opening track and lead-off shot from Slave to the Grind, the record that blew up the band's bubblegum-metal reputation and, in the same swing, became the first hard-rock album to debut at number one on the Billboard 200 in the SoundScan era. Their 1989 debut had floated on power ballads — "18 and Life," "I Remember You" — and the label wanted more of the same; the band handed back a heavier, meaner, downtuned record and put "Monkey Business" first, Rachel Bolan and Snake Sabo's swampy, menacing strut, all swagger and trouble grinning in the doorway.

A full-surface security pass, and the eight places code drifted from its own safety protocols

v0.26 is a security hardening release. It is the result of a full-surface review across the parts of the crate where a mistake costs the most: wire-protocol parsing, the crypto primitives, the C-ABI FFI boundary, identity / token / auth, on-disk storage, and the client SDKs.

Most of the classic traps — the off-by-one slice, the unchecked length prefix, the malleable signature, the path-traversal write — already carry an explicit guard and a regression test pinning it. The eight issues that came out of the pass cluster in one place: where a single piece of code diverged from a safety protocol the rest of the codebase already follows. A blob handle that skipped the quiescing dance every other handle does. An inbound length cast the wide way in one binding and the narrow way in another. A token expiry that had a saturating add but no ceiling. The fixes mostly amount to making the outlier match the rule.

A blob handle that didn't play by the handle rules. The crate documents a per-handle quiescing protocol for exactly one hazard: a foreign thread (a Go cgo callback, a Python thread, a Node worker) sitting inside an FFI call while another thread frees the same handle. Every mesh / cortex / redis handle embeds a small guard, gates each operation on it, and on free leaks the handle box rather than deallocating it — so a racing call always lands on valid memory, sees the "freeing" flag, decrements, and bails. The mesh blob-adapter handle was the one that never got the treatment: it carried only the inner pointer, and its free did an unconditional deallocation. A store / fetch / exists racing a free read freed memory; a second free was a double-free. v0.26.0 embeds the guard, gates every operation on it, and makes free leak the box and drop only the inner — the adapter now follows the same recipe as every handle around it. A regression test pins both properties: an operation on a freed handle returns the null-pointer code instead of corrupting memory, and a double-free is a no-op.

An inbound length cast the narrow way. Inbound nRPC request bodies and the MeshOS causal-event / snapshot-restore payloads were copied from the native buffer with a 64-bit size cast down to a 32-bit signed int. A length with the high bit set went negative and crashed the copy before the handler's panic recovery could catch it; a length at or past 4 GiB modulo 2³² produced a short copy — a truncated body whose framing still claimed the original size, a clean parse-desync primitive. Both are reachable from whatever a peer puts on the wire. One binding file already did this correctly — checking the length against the platform-int maximum and copying through a wide slice — but the inbound trampolines had not been updated, in two separate binding copies. v0.26.0 routes every inbound site through one guarded helper that rejects an over-range length and copies through a wide slice, applied to both copies.

Tokens that could outlive the heat death. A permission token's expiry was a saturating add of issue-time plus requested duration, with no cap on the duration — a caller could mint a token with a TTL of u64::MAX, whose expiry saturated into a timestamp that never arrives. The only way to retire such a token is an advisory revocation floor that has to be distributed out of band and that a given node might never learn to bump. v0.26.0 rejects any TTL past a one-year ceiling at issue time with a typed TtlTooLong error. Delegation only ever copies a parent's expiry, so the bound holds transitively down the whole chain. Long-lived grants now have to be periodically re-issued — which re-checks the issuer's signing key and current policy — and the blast radius of any single leaked token is capped at a year.

Constructors that skipped the guard. The registry-client, fold-query-client, and channel-registration entry points, plus the blob-adapter constructor, dereferenced the inner mesh / redex node after only a null check, with no free-race guard. A concurrent free that won its race left them reading a dropped pointer. Same class as H1, narrower blast radius — these run before the handle is widely shared. v0.26.0 gates each on the relevant handle's guard; the node-clone accessors now hold the guard across the clone and return an Option, and every caller surfaces a null / error result when the handle is being torn down.

Clock skew with no ceiling. The token cache's clock-skew tolerance — a knob for absorbing NTP and container-clock drift — accepted any value. A large skew symmetrically widens every token's validity window: an expired token stays accepted for that many extra seconds, across the whole cache. The default is strict (zero), so this was misconfiguration-gated rather than on by default, but there was no guardrail. v0.26.0 clamps the tolerance to five minutes, which comfortably covers real drift while keeping a fat-fingered config from turning the expiry check into a rubber stamp.

---

Test hygiene

• Every fix that could carry a regression test does. The H1 fix pins that an operation on a freed handle bails with the null-pointer code and that a double-free is a no-op. The H3 fix pins rejection at and past the TTL ceiling and a valid, non-saturating token at exactly the ceiling. The M2 fix pins the skew clamp on both the constructor and the setter. The L3 fix plants a symlink to an out-of-root secret and asserts that fetch, exists, and stream all refuse it.
• A follow-up review caught two things the fixes themselves introduced. Bounding the TTL turned the SDK's infallible token-issue helper — which unwraps the fallible path — into a panic on an over-long TTL; it now soft-clamps to the ceiling instead, matching the existing zero-TTL soft-clamp, with its own release / debug / fallible test trio. The new read-path symlink test was gated to the platforms that can plant a unix symlink, and the blob existence probe re-applied its regular-file contract so a directory sitting at a blob slot is not reported as present.
• The full library test suite passes, including the new regression tests.

---

Breaking changes

TokenError has a new TtlTooLong variant

Additive, but TokenError is a plain enum — downstream code that matches it exhaustively without a wildcard arm will need a new arm for the variant. The binding error-string maps were updated in lockstep (ttl_too_long).

Token TTL is capped at one year

try_issue returns TtlTooLong for any duration past the one-year ceiling; the infallible issue wrapper panics on it (use try_issue for untrusted input). The SDK's infallible issue_token soft-clamps to the ceiling rather than panicking. Callers that were minting multi-year or never-expiring tokens must re-issue inside the bound or move to a periodic re-issue.

Clock-skew tolerance is capped at five minutes

TokenCache::with_clock_skew / set_clock_skew clamp any larger value to five minutes. A config that set a larger skew silently receives the clamp.

New public constants

MAX_TOKEN_TTL_SECS (one year) and MAX_TOKEN_CLOCK_SKEW_SECS (five minutes) are exported from the identity module for callers that want to check before they call.

---

How to upgrade

1. Most consumers — bump the dependency. The fixes are on by default and need no source changes unless you mint tokens with very long TTLs, configure a large clock skew, or match TokenError exhaustively.

2. Token issuers — check your TTLs. Anything past one year is now rejected on the fallible path and clamped on the SDK's infallible path. If you were relying on a never-expiring token, switch to a periodic re-issue — that is the point of the cap. MAX_TOKEN_TTL_SECS is the ceiling to check against.

3. Anyone matching TokenError — add the TtlTooLong arm. Exhaustive matches without a wildcard will not compile until you do.

4. Operators who tuned clock skew — confirm your value. Anything above five minutes is now clamped to it. If you genuinely needed a wider window you were papering over a clock problem; fix the clock instead.

5. Foreign-language callers sharing handles — no API change, but the race is now safe. Sharing a blob-adapter handle across threads and racing a free against an in-flight call no longer corrupts memory — the racing call bails with the null-pointer code. No code change required.

6. Wire format is unchanged; v0.25 and v0.26.0 peers handshake cleanly.

Named after the Dire Straits track that opened side two of Brothers in Arms in 1985 — the one Mark Knopfler wrote standing in a New York appliance store listening to a delivery guy heckling MTV, the one Sting flew in to harmonize the "I want my MTV" hook over a single take. Same wire, same semantics, same surface — money for nothing, and the bytes for free.

One audit pass, two wins, one binary that finally stopped paying for what it wasn't using

The v0.24 release is the result of one perf-audit pass against the nRPC hot path, one binary-size audit against the napi release artifact, and one structural follow-through on a footgun the size audit uncovered. The audit pass found two systemic costs that every nRPC call paid by default: a per-packet tokio::spawn + AEAD encrypt + sendto to emit a StreamWindow grant on each accepted inbound packet, and a per-reply roster lookup + ACL check + subnet filter + per-recipient Vec<Bytes> fan-out for response legs that already knew the caller. The size audit found regex — pulled into every binding's release artifact by an unread compiled_patterns field and a single matcher variant that most consumers never touched — was costing ~1.10 MiB on the napi win-x86_64 cdylib alone, and that the feature-disabled fallback silently returned empty matches.

The release's organizing observation: when the substrate emits work that the caller has already computed, the work is free to skip. The grant drainer skips the per-packet spawn / encrypt / sendto by coalescing every (session_id, stream_id) grant in a per-mesh map that a single drainer task drains on a 1 ms tick. The direct-response fast path skips the roster lookup by caching the AEAD-verified from_node at the bridge layer and routing the reply through publish_to_peer directly. And the regex-gate skips the binary cost entirely for consumers who don't construct a Regex matcher — and when they do construct one against a regex-less build, the binary now tells them so loudly instead of silently returning nothing.

Below: the wins, grouped by where they fire.

---

nRPC perf — drainer-batched grants, direct-send responses

PERF_AUDIT_2026_05_19_NRPC.md (the audit doc shipping alongside this release) flagged two costs that hit every nRPC call regardless of payload shape, contention, or transport. v0.24 closes both.

T1.1 — StreamWindow grant batching via a per-mesh drainer. The receive path previously emitted one wire grant per accepted packet: a tokio::spawn + AEAD encrypt + sendto round-trip per inbound packet, even for unary RPC where the response leg would have replenished credit on its own. v0.24 decouples emission from the receive path entirely:

• Per-MeshNode state: pending_stream_grants: Mutex<HashMap<(session_id, stream_id), PendingStreamGrant>> + a single Notify.
• Receive path now does one lock + insert + notify_one per accepted packet — no spawn, no encrypt, no sendto.
• A per-mesh drainer task (spawn_stream_grant_drainer_loop) wakes on the Notify or on a 1 ms safety-net interval, swaps the map out with std::mem::take, and emits one wire grant per unique (session_id, stream_id).
• Same-key receives between drain cycles overwrite the value (latest-wins). Grants are authoritative — every emission carries the receiver's full total_consumed — so the latest entry subsumes every pending earlier one and the drainer never undercounts.

Supersedes a threshold-coalesce attempt (c38f01f5) whose RxCreditState::take_pending_grant heuristic deadlocked any sender configured with a tx_window smaller than the receiver's coalesce threshold. The receiver auto-creates streams with DEFAULT_STREAM_WINDOW_BYTES (64 KiB) regardless of the sender's config, so a sender opening a 512-byte stress stream (sdk/tests/mesh_stream_backpressure.rs) would stall waiting for a grant that wouldn't fire until 32 KiB of consumption. The drainer pattern has no threshold — every accepted packet enqueues, every drain cycle emits — so the deadlock can't recur.

T1.2 — Direct-send RPC responses via publish_to_peer. The four reply emit sites (unary, server-streaming, client-stream terminal, duplex chunks) previously built a ChannelPublisher and called mesh.publish, which runs the roster lookup + ACL check + subnet filter + per-recipient Vec<Bytes> alloc fan-out path before forwarding to publish_to_peer anyway. The response leg already knows the caller from the AEAD-verified inbound from_node.

• Per-service RpcOriginNodeCache (Arc<DashMap<origin_hash, from_node>>) populated by the bridge from the inbound from_node at REQUEST receive time.
• New publish_response_to_caller helper consults the cache, then falls back to the mesh's global origin-hash reverse index, then finally to mesh.publish — preserving correctness for loopback / test paths that emit with from_node==0.
• Applied to every reply shape: unary, server-stream chunks, client-stream terminal response, duplex chunks.

Benchmarks (May 19 audit hardware, 14900K, c128 client mesh):

benchmark	baseline	v0.24 (drainer + direct-send)	delta
nrpc_qps c1/32B	69.6 µs	42.5 µs	-39%
nrpc_qps c128/32B	1.84 ms	1.12 ms	-39%

Per-RT, T1.2 alone clips ~3-8 µs off the response publish path; the rest of the win comes from T1.1's elimination of the per-packet grant overhead. The c128 case scales the win proportionally because the saved syscalls compound across concurrent in-flight RPCs.

Test posture. All 36 nRPC integration tests + 41 session unit tests + the previously-failing sdk/tests/test_sdk_send_with_retry_succeeds_through_backpressure are green. The drainer is exercised under both the small-window stress path (the test that deadlocked the v1 threshold-coalesce approach) and the c128 saturation path.

---

regex is now an opt-in Cargo feature (-1.10 MiB on every binding artifact)

regex was unconditional in Cargo.toml and pulled in by every consumer of net-mesh — the Node/Python/Go bindings, the CLI, downstream SDK users. Two consumers held references:

• behavior::safety::SafetyEnforcer::compiled_patterns — held but unread (marked #[allow(dead_code)]); the safety enforcer never wired the pre-compiled pattern fast-path that field was reserved for.
• behavior::fold::capability_aggregation::TagMatcher::Regex — live, but the variant is one of six matcher kinds; consumers who never construct a Regex matcher pay the binary cost for zero functional benefit.

The cost is non-trivial: ~1.10 MiB on the napi win-x86_64 release artifact (9.49 MiB → 8.39 MiB after gating). The same delta lands on every binding (Python wheel, Go cdylib, C ABI, CLI).

v0.24 makes regex optional and gates the live usage:

• Cargo.toml: regex = { version = "1", optional = true }; the previously-empty regex = [] alias becomes regex = ["dep:regex"].
• capability_aggregation.rs: the wire-format TagMatcher::Regex variant stays in the enum unconditionally — peers exchanging serialized matchers must keep working regardless of the receiver's feature set. The CompiledMatcher::Regex arm and its matches_one branch gate on #[cfg(feature = "regex")].
• safety.rs: the compiled_patterns field and its initializer gate on the feature.

Consumers who want regex matching turn it on:

cargo add net-mesh --features regex

The Node / Python / Go bindings re-export the feature through their own feature lists; downstream binding consumers flip it in their package.json / pyproject.toml / Go build tags the same way they flip every other binding feature.

---

TagMatcherError::RegexNotBuiltIn — explicit error, no more silent empty

The first cut of the regex gate routed TagMatcher::Regex to MatchesNothing on regex-less builds. Compiled cleanly, preserved the existing "invalid pattern → matches nothing" fail-closed contract — and silently returned empty results that looked indistinguishable from "no entries match this pattern." Operators couldn't tell whether their query was wrong or the binary couldn't evaluate it.

v0.24 replaces the silent fallback with a structured error and a loud panic at the call site:

• New TagMatcherError::RegexNotBuiltIn { pattern } carries the offending pattern + an actionable Display message ("Rebuild with --features regex or use a different matcher").
• New TagMatcher::validate(&self) -> Result<(), TagMatcherError> for proactive callers (RPC handlers, language-binding constructors, CLI parsers) that accept user-supplied matchers and want structured failure surfacing.
• compile() panics on the regex-less-build + Regex-variant combo with the same Display message. Callers that skipped validate() see the build-time-config mismatch loudly at first use rather than silently for the lifetime of the deployment.

Wire format is unchanged: TagMatcher::Regex stays in the enum unconditionally so peers can still exchange it. The doc on the variant calls out the gate and the validate-first contract.

Two new tests pin the behavior under #[cfg(not(feature = "regex"))]:

• matcher_regex_without_feature_validate_returns_explicit_error — surfaces the structured error.
• matcher_regex_without_feature_aggregate_panics_with_actionable_message — surfaces the panic message.

The existing matcher_regex_with_invalid_pattern_matches_nothing test runs under #[cfg(feature = "regex")] only — its premise (regex crate compiles and then rejects a bad pattern) requires the feature.

---

async-nats 0.49 — PublishErrorKind::MaxPayloadExceeded classified as fatal

The Renovate-driven async-nats 0.23 → 0.49 bump added a new PublishErrorKind::MaxPayloadExceeded variant, which broke the exhaustive match in JetStreamAdapter::is_transient_error. v0.24 classifies the variant as fatal alongside StreamNotFound and the WrongLast* family — oversized payloads will not become recoverable on retry, and retrying would loop until an operator intervenes (the same production-down scenario that drove the Other → fatal classification in v0.20.2).

No SDK-surface changes. The classification matrix grows one structural-fatal row:

                              transient?  retry?
TimedOut                          yes       yes
BrokenPipe                        yes       yes
MaxAckPending                     yes       yes
StreamNotFound                    no        no
WrongLastMessageId                no        no
WrongLastSequence                 no        no
MaxPayloadExceeded   (new)        no        no
Other                             no        no  (logged before return)

Operators who hit the new variant in production logs are getting a hard signal that a producer is exceeding the stream's max_msg_size config — the fix is upstream (chunk the payload, raise the stream limit), not in the retry loop.

---

Test hygiene

• Perf-audit doc shipped in tree. docs/plans/NRPC_FLAMEGRAPH.md lands alongside the perf wins — the flame-graph methodology, the 14900K bench rig config, and the before/after numbers are pinned in the repo so the next perf pass starts from a known reference frame.
• The previously-failing backpressure test now passes. sdk/tests/mesh_stream_backpressure.rs::test_sdk_send_with_retry_succeeds_through_backpressure was deadlocked under the v1 threshold-coalesce approach (small-window sender + receiver's default 64 KiB stream → no grant ever fired). The drainer pattern has no threshold, so the test passes.
• cargo clippy --features meshos,deck,aggregator --all-features --all-targets -- -D warnings clean. Strict floor from v0.20.2 stays armed across the feature-flagged regex split.
• cargo doc --features meshos,deck,aggregator --no-deps clean under RUSTDOCFLAGS="-D warnings". Intra-doc links across the new TagMatcherError, validate(), and compile() panic docs all resolved.
• Feature-matrix CI. Both the default (regex-on, matches every existing binding default) and the regex-off path (consumers who explicitly disable regex to trim binary size) run their unit + integration suites. The two regex-off-only tests run only in the regex-off job; the live-regex test runs only in the regex-on job.
• Codecov coverage unchanged in posture — ~90% substrate, informational on CI status.

---

Breaking changes

regex is no longer pulled in by default for direct net-mesh consumers

Cargo.toml flips regex from an unconditional dep to optional = true. The regex = [] feature alias becomes regex = ["dep:regex"]. Direct net-mesh consumers who relied on transitive access to the regex crate via net-mesh need to depend on regex directly. Downstream consumers who construct TagMatcher::Regex must enable --features regex (or the matcher will return a structured error / panic per the new contract below).

The Node, Python, and Go binding default feature sets include regex — most users see no behavior change unless they intentionally trim the binding's feature list.

TagMatcher::Regex on a regex-less build now errors or panics instead of silently matching nothing

The previous regex-feature-off fallback was MatchesNothing — invisible to the caller. v0.24 surfaces it:

• Callers using TagMatcher::validate(&matcher)? get TagMatcherError::RegexNotBuiltIn { pattern }.
• Callers who skip validation and pass the matcher straight to Fold::aggregate / Fold::capacity_ranking get a panic with the same actionable message.

The previously-pinned "invalid pattern matches nothing" contract still holds with the feature on — an invalid pattern (e.g. unbalanced parens) compiles to CompiledMatcher::Regex { re: None } and matches nothing, exactly as before. The behavior change is strictly for the feature-off path.

JetStreamAdapter::is_transient_error classifies MaxPayloadExceeded as fatal

Wire-shape compatible — the PublishError envelope is async-nats's own type. Behavior change: an oversized publish previously hit the catch-all branch (and now panics at the exhaustive-match compile error if anyone has been pinning async-nats 0.49 without the variant arm). v0.24 classifies it as fatal so the retry loop terminates and the underlying misconfig surfaces.

Per-packet StreamWindow grant emission is gone (internal-only break, observable as wire-rate)

The receive path no longer fires one grant per accepted packet. Operators watching wire traffic with tcpdump see fewer grant control packets per RPC — on a unary call, typically one terminal grant instead of N (one per inbound packet). Grants remain authoritative on every emission, so backpressure semantics are unchanged from the caller's perspective.

Direct-send response routing falls back to mesh.publish only when no peer hint resolves

Internal-only break. The four serve_rpc_* reply emit sites now consult a per-service RpcOriginNodeCache and fall back to a global origin-hash reverse index before reaching mesh.publish. Loopback / test paths that emit with from_node==0 still resolve through mesh.publish as before; production paths get the direct route. Downstream consumers who hooked the mesh.publish path for response-leg telemetry will see fewer events from that hook on the response side.

STREAM_GRANT_DRAIN_INTERVAL is a new private constant

Hard-coded to 1 ms. Not exposed as a tunable. The constant lives in adapter/net/mesh.rs and is documented inline alongside the drainer; a future config tunable is a one-line plumbing change against the constant's call site.

PendingStreamGrant is a new private struct

Internal to adapter/net/mesh.rs. Captures the AEAD session (cipher + packet pool + next_control_tx_seq) and the peer's wire address. Not exported; the per-binding APIs are unchanged.

---

How to upgrade

1. Rust consumers — update the dependency to 0.24. No source changes required unless you (a) construct TagMatcher::Regex directly and don't enable the regex feature, or (b) match exhaustively on PublishErrorKind in your own code. The former: add validate() ahead of compile, or enable the feature. The latter: add MaxPayloadExceeded => ... to your match.

2. Operators with TagMatcher::Regex in their query mix — pin the regex feature explicitly. Direct net-mesh consumers: cargo add net-mesh --features regex. Bindings: enable the binding's regex feature flag (Node + Python + Go default to on; downstream wrappers may differ). The structured TagMatcherError::RegexNotBuiltIn shows up in validate() results when the build is wrong; the panic at Fold::aggregate shows up at first use when validation is skipped.

3. Operators with binary-size budgets — flip regex off explicitly. The napi win-x86_64 artifact drops 1.10 MiB. Downstream binding builds: pass --no-default-features and enumerate the features you do want (substitute the binding's own default list minus regex). Verify by grepping cargo tree -e features for regex — it should not appear.

4. Operators watching nrpc_qps benchmarks — expect the -39% delta to land out of the box. No config knobs to flip. The drainer's 1 ms interval is hard-coded; the response cache populates automatically on first inbound request per origin.

5. Operators on async-nats 0.49 or later — the MaxPayloadExceeded classification fix is automatic. A producer hitting the variant gets a hard fatal in the logs (look for the existing JetStream publish error tracing); previously this same path would loop forever silently as part of the catch-all. Upstream fix: chunk the payload or raise the stream's max_msg_size.

6. Downstream consumers who hook mesh.publish for response-leg telemetry — re-wire to the substrate observer. The four reply sites now bypass mesh.publish on the production path. The substrate observer surface from v0.23 (setObserver / set_observer / SetObserver) fires on every RPC reply and is the supported way to observe the response leg.

7. No CI config change required. Strict clippy floor stays armed; rustdoc warnings stay denied; the feature-matrix job runs both regex-on and regex-off paths. The Renovate config tracks async-nats minor bumps; future bumps that add PublishErrorKind variants will fail the exhaustive match at compile time, exactly as 0.49 did.

8. Operators — bump the binary. Pre-built net-mesh, net-deck, net-aggregator-daemon archives land for every supported target (Linux x86_64 / aarch64, macOS x86_64 / aarch64, Windows x86_64). Wire format is unchanged from v0.23; mixed-version fleets handshake cleanly and the v0.23 TypedMeshRpc.Regex variant transmitted from a regex-on peer to a regex-off peer surfaces as the structured error on receive instead of silent empty.

9. Downstream Go binding consumers — ABI version unchanged. NET_RPC_ABI_VERSION stays at 0x0004. No symbol additions in this release.

Named after Bob Dylan's 1967 cut from John Wesley Harding — the one Jimi Hendrix took six months later and turned into his own song so completely that Dylan started covering Hendrix's arrangement instead of his own ("he found things in the song that I didn't realize were there"). Twelve lines, three verses, no chorus: the joker tells the thief there must be some way out of here, the thief replies that the hour is getting late, and the camera pulls back to a watchtower where princes watch the women come and go and two riders are approaching from outside the frame. The whole song is built around the vantage point — somebody up on the parapet, looking down at the territory below, naming what they see. v0.22 puts that vantage point in the substrate. An aggregator daemon sits one tier up from a source subnet, subscribes to that subnet's detail channels through the existing gateway, summarizes what it sees, and publishes the summary to channels visible at the parent or peer tier. The mesh already had four-level hierarchical SubnetId on every packet, a gateway that enforced visibility at subnet boundaries by reading header fields only, label-based subnet assignment, and replica groups for any daemon role. v0.21 was about shrinking the gap between call and arrival on the hot path; v0.22 is about giving every tier a watchtower without inventing a parallel scoping mechanism. One generic state-aggregation framework replaces three would-be-separate fold implementations. One aggregator daemon role, deployed via the existing replica-group infrastructure, bridges tiers — N watchers per subnet, all publishing independently, subscribers picking the freshest by generation. One RPC surface lets operators spawn, scale, and query those watchers from any node, any language, any process. And one Deck retab puts the whole topology on the cyberdeck so the operator has the same vantage point the substrate just built.

One framework, three folds, watchers in front of all of it

The v0.22 release is the result of four planning passes that converged on the same insight: the substrate already had the primitives for million-node scale, but three layers above it were duplicating work to consume them. The capability index was a bespoke per-class store with its own subscription model and its own eviction; the routing table was a pingwave-driven sorted-by-metric thing with its own staleness sweeper; reservations were going to be a third bespoke layer doing the same shape of work for a third domain. The fold framework lands one generic runtime parameterized by a typed FoldKind trait — apply, expire, query, snapshot, recovery, audit emission, metrics — and three concrete instantiations on top of it. The legacy CapabilityIndex and the pingwave-driven routing table delete in the same diff that lands their fold replacements. No bridges, no dual-publish, no transition window.

Above the folds, the aggregator role lands as a normal daemon — but a daemon with a lifecycle. The substrate gets a new LifecycleDaemon async sibling trait to MeshDaemon (the existing sync/WASM-friendly trait), a LifecycleHandle RAII wrapper that owns the daemon's tokio loop, and a generic LifecycleGroup<L> that manages N replicas of any LifecycleDaemon as a unit. Aggregators are the first application; future tier services (market matchers, settlement bridges, reputation oracles) reuse the primitive. Placement spreads across failure domains via the scheduler; per-replica health drives auto-replacement via a background HealthMonitor with exponential backoff; a register_with_monitor constructor wires registry + monitor together so the operator never has to thread them by hand.

On top of the lifecycle layer, the aggregator.registry RPC service lets any node enumerate, spawn, scale, and unregister aggregator groups on any other node. The new turnkey net-aggregator-daemon binary boots from a TOML config, registers templates the operator can instantiate by name, defaults to auto-respawn-on-failure, and prints a single JSON bootstrap line on stdout for tools that need its bound address and pubkey. Five language bindings (Rust, TypeScript, Python, Go, C) get the same RegistryClient + FoldQueryClient surface with the same typed error kinds and the same wire contract locked in a single table. The CLI grows remote-attach: net aggregator query / spawn / scale / ls --remote against --node-addr <ip:port> --node-pubkey <hex> --node-id <n> round-trips through a live daemon. The Deck grows three new tabs and a focus page so operators can see subnet hierarchy, gateway state, and aggregator health without leaving the cyberdeck.

Below: the wins, grouped by where they fire.

---

Multi-fold framework: one runtime, three typed instantiations

The Fold<K> runtime is the new spine of the substrate's typed-state layer. One implementation handles every fold; concrete folds are trait impls.

FoldKind trait + Fold<K> runtime. FoldKind is parameterized by Key, Payload, Query, Result, and Index associated types; the fold author supplies key_for, merge, build_index, query, and optional audit_event. The runtime owns FoldState<K> (primary HashMap<K::Key, FoldEntry<K>> + a reverse HashMap<NodeId, HashSet<K::Key>> for O(1) node eviction), the expiry task, the audit sink, and the metrics handle. Snapshot/restore round-trips identical state — restored entries are naturally superseded by live announcements with higher generation numbers, so warm starts don't need any "I'm catching up" coordination.

SignedAnnouncement<P> wire format. One ed25519-signed envelope carries kind (the u16 KIND_ID that names the fold), class (the fold-specific sub-bucket — capability class hash, routing tier, reservation pool), node_id, generation, announced_at micros, ttl_secs, flags, and the typed payload. Subnet scope is not in the envelope — every packet already carries NetHeader.subnet_id, and the substrate's existing ChannelConfig::visibility (SubnetLocal / ParentVisible / Exported / Global) plus SubnetGateway handle scoping at the wire layer. Folds reuse this; they don't invent a parallel scoping model. The dispatch layer reads kind from the announcement header, looks up the registered fold instance, verifies the signature, and calls Fold::apply. Wire encoding is postcard; the format is versioned via the KIND_ID namespace.

CapabilityFold — replaces the legacy CapabilityIndex outright. Each (capability class, node) is one entry; subscribers learn which nodes are in which classes. The legacy CapabilityIndex and every caller (MeshNode::capability_index, Scheduler::place_*, ReplicaGroup / ForkGroup / StandbyGroup placement paths, the FFI surface, the Deck capability panel) was rewired in one diff. The inverted indices (by_tag, by_region, by_state) are part of the fold's Index type; tag-inverted lookup runs in the same shape it did pre-cutover, but now under the generic runtime with snapshot/restore and audit emission for free.

RoutingFold — replaces the pingwave-driven RoutingTable outright. Destination is the key; multiple announcements per destination from different routers compete via metric-based merge. The Router::lookup and MeshNode::dispatch_packet call sites rewired in the same diff. Pingwave packets become SignedAnnouncement<RouteAnnouncement> publishes on the fold:route: channel — same wire RTT measurement, new envelope. The route-staleness sweeper goes away; TTL expiry on the fold runtime handles it.

ReservationFold — new typed fold for single-holder resources. Each resource has at most one active reservation; ReservationState::Free | Reserved { holder, until } | Active { holder, job_id }; merge enforces a state machine (legal transitions accepted, illegal rejected with audit event). The same owner can transition through states; a different owner can only claim when the current state is Free. The fold's per-state summarizer derives stable bucket labels from a fixed-label match (not from format!("{state:?}")), so summary cardinality stays bounded regardless of how many distinct holders pass through.

Subscription dispatch + FoldRegistry. One FoldRegistry per node owns the HashMap<u16, Arc<dyn FoldDispatch>>. Channel-layer messages route by kind ID; signature verification happens at dispatch time using existing identity machinery. Replay protection is generation comparison; reorder protection is the same.

Audit + snapshot + metrics integration. Per-fold metrics: fold_entries_total, fold_applies_total{outcome}, fold_expiries_total, fold_queries_total, fold_query_duration, fold_apply_duration, fold_subscription_lag. Audit events: FoldEntryCreated / Replaced / Expired / Evicted / Rejected flow through the existing audit chain. Snapshots serialize at configurable cadence (default 5 min) and on graceful shutdown.

---

Aggregator daemons: a lifecycle layer above MeshDaemon

The aggregator role is inherently async (tokio::interval + mesh.publish().await); the existing MeshDaemon is documented sync-only / WASM-compatible (process(&CausalEvent) -> Vec<Bytes>). v0.22 introduces an async sibling and builds the aggregator on top.

LifecycleDaemon async sibling trait + LifecycleHandle RAII wrapper. LifecycleDaemon is the trait async daemons implement (async fn on_start, async fn on_stop, etc.); LifecycleHandle::start(daemon) owns the tokio loop and stops it cleanly on drop. The shutdown-aware tick loop checks the shutdown flag between publishes, so a long-running publish().await doesn't get its task dropped mid-flight by the backstop timeout. The backstop itself bumped from "summary interval + 100 ms" to a value that absorbs realistic publish latencies under load.

LifecycleGroup<L> — N-replica HA generic over the lifecycle daemon. Hoisted out of an aggregator-specific group type so any future tier service uses the same primitive. Deterministic per-replica keypairs via derive_replica_keypair(group_seed, index); spawn_with_placement consults the scheduler to spread replicas across failure domains within the source subnet; requirements() on the trait flows through to placement constraints. In-place grow/shrink via new add_replica (takes a factory closure, returns the new index) and remove_last (returns the stopped replica's Arc); deterministic-last-as-victim keeps the lowest-indexed replicas across resizes so identity continuity is preserved.

ReplicaHealth + LifecycleGroup::replace. Per-replica liveness is derived from start_instant + generation (no last_tick_at field needed — generation already advances on every successful summary). Unhealthy replicas can be swapped via replace(index, new_daemon); group-level health is "≥1 healthy replica."

HealthMonitor — background auto-respawn driver. Periodic per-replica health checks; failed replicas get re-spawned via a cached factory with exponential backoff so a persistently-broken daemon doesn't spin in a respawn loop. Configurable; register_with_monitor is the one-call constructor that wires registry + monitor together as the operator-facing entry point.

AggregatorDaemon as a LifecycleDaemon. AggregatorConfig { source_subnet, summary_visibility, summary_targets, fold_kinds, summary_interval, custom_summarizers }. On start, subscribes to source-subnet detail channels for each configured fold kind; on tick, walks each fold's Summarizer to produce SummaryAnnouncements and publishes them at the configured visibility. Validates at boot via a dry-run AggregatorDaemon::new so a misconfigured template is rejected on the operator's terminal, not on the first tick.

All replicas publish independently. No election machinery; subscribers see N summary announcements per cycle and the fold's merge picks the latest by generation. Operator can scale_to(1) to reduce summary traffic when availability isn't the constraint. State across re-placements rebuilds from incoming channel announcements + TTL refreshes within one TTL cycle (~30-60s); other replicas in the group publish full summaries during rebuild.

Built-in summarizers per fold. CapabilityFoldSummarizer (count by class + state, aggregate hardware capacity, distribution across sub-subnets) and ReservationFoldSummarizer (count by resource class + state, fixed-label state buckets). Routing is intentionally not summarized — routing wants full detail or none. Custom summarizers are Rust-only; bindings get the two built-ins via the daemon's template registry.

AggregatorRegistry on MeshNode. First-class registry surface — net aggregator inspect reads it; the RPC service publishes from it; MeshOS inspection surfaces include aggregator groups alongside DaemonRegistry's mesh-daemon entries. Holds LifecycleGroup directly (rather than wrapping it), so registry entries carry enough state to fill RegistryGroupSummary fields without a second indirection.

---

Turnkey net-aggregator-daemon binary

For operators who don't want to embed the substrate in their own process, the new net-aggregator-daemon crate ships a turnkey binary + library that boots from a single TOML file.

Templates + groups. [[template]] blocks declare named aggregator specs (source_subnet, summary_visibility, fold_kinds, summary_interval); [[group]] blocks instantiate templates at boot. Templates are validated up-front via a dry-run AggregatorDaemon::new — if a template's config is broken, the daemon fails on start with a copy that points at the bad field, not silently at the first tick.

Spawn / Unregister / List / Scale via RPC. Once running, the daemon serves the aggregator.registry RPC service. Operators ship a config with zero [[group]] blocks and spawn dynamically via the wire, or pre-declare groups in TOML and let the wire surface only handle scale + lifecycle. The Spawn { template_name, group_name, replica_count } op resolves the template, derive_seed_from_name (blake3, deterministic) computes the group seed from the operator-supplied name, and a factory closure constructs each replica with the resolved spec.

Auto-respawn by default. HealthMonitor is installed by default; operators who want bare-metal control opt out. Replica failures trigger respawn via the cached factory with exponential backoff on persistent failures.

--print-bootstrap flag. Emits a single JSON line to stdout before entering the wait loop: {"node_id": N, "bound_addr": "127.0.0.1:54321", "public_key_hex": "abcd…"}. Binding test fixtures and CLI subprocesses read the first stdout line, parse it, and use the triple to drive their handshake — no more parsing tracing output.

Parallel group spawn at boot. Groups declared in TOML start their replicas in parallel via try_join_all (replica on_start is independent within a group; group-level startup is independent across groups). Boot time on a 4-group × 3-replica config drops from sequential 4 × 3 × on_start_time to max(on_start_time).

AggregatorSpec unification. GroupConfig and TemplateConfig unify behind one AggregatorSpec; the spawn-and-register path is shared between boot-time groups and RPC-spawned groups.

---

Cross-subnet detail-on-demand RPC

When a subscriber sees a summary (via ParentVisible / Global summary channels) and wants detail from the source subnet, it RPCs the aggregator. The wire and client surface are first-class.

FoldQueryService (fold.query). Aggregator daemons install the service automatically. Query shape: (kind: u16, class: u64, query: Bytes) → Bytes (fold-specific, postcard-encoded). The aggregator answers from its local fold state; the gateway forwards the RPC based on subnet_id + channel visibility per the substrate's normal routing. No new wire protocol, no special-case routing.

FoldQueryClient with cache semantics. query_latest(target, kind) consults a per-target LRU keyed on (target_node_id, kind) with DEFAULT_QUERY_CACHE_TTL (5s) before going to the wire; query_summarize_now(target, kind) forces a fresh tick on the host and bypasses the cache. with_ttl / with_deadline builders override defaults; invalidate_cache / invalidate_target give explicit eviction. Same cache semantics across every language binding.

Discovery via the registry. Replicas are tagged with role:aggregator; the source subnet is in their identity. route_event on the underlying group picks the closest healthy replica.

Copy-on-write latest buffer. The aggregator's latest-summaries buffer is Arc<Vec<SummaryAnnouncement>> — tick_once returns its novel batch directly, SummarizeNow reads it without re-copying, and the buffer evicts oldest-first via VecDeque.

---

aggregator.registry RPC + RegistryClient

A single RPC service drives every aggregator operation across the wire.

Wire surface (RegistryRequest / RegistryResponse).

• List → Groups(Vec<RegistryGroupSummary>) — every registered group with per-replica health.
• Spawn { template_name, group_name, replica_count } → Spawned(RegistryGroupSummary) — daemon resolves the template, derives the seed from the group name, spawns N replicas via the lifecycle group.
• Unregister { group_name } → Unregistered { existed } — stops the group cleanly.
• Scale { group_name, template_name, target_replica_count } → Scaled(RegistryGroupSummary) — dedicated in-place grow/shrink; held replicas keep their tokio loops and their identities across the resize (no Unregister + Spawn churn). The server re-resolves the template and compares against the group's stored source_subnet + fold_kinds so a --template typo is caught before any state change.

Server split. The registry service splits into RegistryReadHandler (List-only — installable without a spawner) and RegistryHandler (full read + write). Read-only deployments don't pull in spawn-side dependencies.

RegistryClient + BoundRegistryClient. RegistryClient::new(mesh).with_deadline(d).list(target_node_id) / spawn(...) / unregister(...) / scale(...). BoundRegistryClient::for_node(mesh, target_node_id) binds the target once so subsequent calls don't repeat it.

Typed error discrimination. RegistryClientError { Transport, Codec, UnknownTemplate, DuplicateGroupName, SpawnRejected, SpawnNotSupported, ScaleRejected, UnknownGroup, Server(detail) } — kind discrimination flows through to every language binding's native error type.

Wire metadata on RegistryGroupSummary. Carries name + group_seed (32 raw bytes → 64-char lowercase hex in language SDKs) + source_subnet + fold_kinds + replicas: [{generation, healthy, diagnostic, placement_node_id}]. The source_subnet + fold_kinds fields land in the same wire bump as Scale so net aggregator ls --remote renders the full spec without a separate Describe op.

Parallel scale grow. Scale-up grows via a bulk add_replicas helper that runs each replica's on_start in parallel via try_join_all. Same shape as boot-time parallel group spawn.

typed_call helper. A thin MeshRpc::typed_call wrapper carries the postcard codec + deadline plumbing for both FoldQueryClient and RegistryClient; client code stops re-implementing the marshal-call-unmarshal-translate-error chain per surface.

---

CLI remote-attach

The CLI grows the ability to drive a remote daemon, not just inspect the local one.

CliContext::with_mesh + remote-attach flags. CliContext now optionally carries an Arc<MeshNode> constructed at build time when --node-addr <ip:port> --node-pubkey <hex> --node-id <n> are passed (or the --remote <NAME> shortcut pulls all three from a named profile). The local mesh boots on 127.0.0.1:0 with a PSK from the profile, connects to the remote daemon via the routed handshake path (see below), and starts the dispatch loop before any verb runs.

net aggregator query / spawn / scale / ls against live daemons. Each verb consumes ctx.mesh_node() and dispatches via the typed client.

• query --kind <hex> → FoldQueryClient::query_latest (or --fresh → query_summarize_now). Output renders the SummaryAnnouncements as JSON via the existing SummaryRow shape.
• spawn --template <NAME> --name <NAME> --replica-count <N> → RegistryClient::spawn. --source-subnet is gone from spawn — the template owns it, and the daemon resolves it on the wire side.
• scale --template <NAME> --name <NAME> --replica-count <N> → RegistryClient::scale. Atomic in-place resize; held replicas keep their generations across the call.
• ls --remote → RegistryClient::list. Renders source_subnet + fold_kinds + per-replica rows from the wire shape.

Routed handshake via connect_via. The substrate's dispatch loop drops direct handshake msg1 packets from peers it hasn't pre-accepted — only the initiator-side has a post-start registry; the responder side was explicitly deferred. CLI subprocesses generate fresh ephemeral identities, so the daemon can't pre-accept them. The CLI now connects via connect_via (routed) — handle_routed_handshake Case 2 already accepts msg1 from fresh initiators against a running dispatch loop. Substrate change: connect_via populates addr_to_node[relay_addr] via entry().or_insert(...) (preserves true multi-hop semantics when relay ≠ final dest), and honors the same handshake_retries knob as direct connect.

Profile + flag precedence. [default].psk_hex + [default].node_addr / node_pubkey / node_id in the CLI config serve as bootstrap shortcuts when always pointing at the same daemon; flags override. Bad pubkey / wrong PSK / wrong node_id all map to typed CliError::RemoteAttach with exit code 6 ("connection / handshake failure").

CLI integration test. cli/tests/aggregator_remote.rs boots net-aggregator-daemon (in-process via the library helper, not as a subprocess — same trick the bootstrap pin test uses), reads node_id / bound_addr / public_key from the booted handle, then invokes each verb via assert_cmd::Command::cargo_bin("net") and asserts exit codes + JSON shapes. Positive paths plus bad pubkey (exit 6), wrong PSK (exit 6), unknown template (exit 3).

---

SDK surface across five languages

Every operator-facing aggregator surface ships in Rust, TypeScript, Python, Go, and C — same wire types, same error kinds, same factory-callback infrastructure where applicable.

net_sdk::aggregator module (Rust). Re-exports the client-only types (RegistryClient, FoldQueryClient, error types, default constants) plus the daemon-author surface (AggregatorConfig, AggregatorDaemon, AggregatorRegistry, LifecycleGroup, HealthMonitor, Summarizer, the two built-in summarizers, the registry service installers). BoundRegistryClient::for_node binds a target id once so subsequent calls don't repeat it. install_default_service is the one-call read-only registry installer. Aggregator is promoted to a first-class default SDK feature flag — operators don't opt in via --features aggregator; it's on by default everywhere the SDK is consumed.

TypeScript (NAPI + @net-mesh/sdk). import { RegistryClient, FoldQueryClient } from '@net-mesh/sdk'. Constructors take a MeshNode; withDeadline(ms) / withTtl(ms) are builders; ops return promises. Group seeds are 64-char lowercase hex strings (BigInt is awkward at 32 bytes); u64 fields are BigInt. Errors are JS class RegistryClientError extends Error with kind: string + optional serverDetail.

Python (PyO3). from net_mesh.aggregator import RegistryClient, FoldQueryClient. asyncio futures via pyo3-asyncio (already in the binding's dep set). Returned shapes are dicts; errors are typed subclasses of RegistryClientError (UnknownTemplate, DuplicateGroupName, SpawnRejected, SpawnNotSupported, etc.).

Go (CGO). net_mesh.NewRegistryClient(mesh).List(ctx, targetNodeID) / .Spawn(...) / .Scale(...) / .Unregister(...). context.Context carries the deadline (honors ctx.Deadline() if set, falls back to the client's configured default). RegistryClientError { Kind, Detail } implements error + matches via errors.Is. A consumer-side Go wrapper around the cgo cdylib keeps the test surface idiomatic.

C ABI (in the main net-mesh cdylib). net_registry_client_new / free / with_deadline / list / spawn / unregister. Errors as net_registry_error_kind_t discriminant + net_registry_last_error_detail accessor. Also: net_visibility_t (GLOBAL / PARENT_VISIBLE / SUBNET_LOCAL) + net_register_channel(mesh, name, visibility) — C consumers can now configure channels with the visibility tier, not just read snapshots.

Wire contract locked across languages. One table fixes group_seed encoding (32 raw bytes → 64-char hex), u64 marshaling per language, deadline carriers (TS: number ms; Py: float seconds; Go: time.Duration), and the canonical error-kind string set (transport, codec, unknown-template, duplicate-group-name, spawn-rejected, spawn-not-supported, unknown-group, scale-rejected). Bindings that diverge fail their compatibility test.

---

Deck: subnets, gateways, aggregators as first-class tabs

The cyberdeck grows three new tabs in the tab strip plus a focus page that drills into a single subnet.

Tab strip overflow + horizontal scrolling. The strip scrolls horizontally to keep the current tab visible; trailing letter-key hints render on overflowed entries so operators can still hit them by key. SUBNETS, GATEWAYS, AGGREGATORS, and AUDIT join the strip alongside the existing tabs.

SUBNETS tab. Cursor-navigable table of subnets with PARENT / HEALTH / AGG columns. Local subnet renders a LOCAL: yes/— marker (the prior name-highlighting was visually noisy and dropped). Pressing Enter drills into a per-subnet focus page.

SUBNETS focus page. Per-subnet health rollup at the top; members render via the shared NODES table widget so cursor + filter behavior matches the main NODES tab. The focus title pops off the redundant id row.

GATEWAYS tab. Cursor-navigable per-channel rows with CHANNEL / VIS / REACH columns — operator sees, at a glance, which channels have which visibility and which subnets they're reaching. Forwarded / dropped counters render in the existing rollup section.

AGGREGATORS tab. Cursor + scrolling over the registry snapshot. Live read of AggregatorRegistry::snapshot (which bundles every field a renderer needs in a single lock — no fan-out reads per row).

Demo fixtures. deck::demo::fixtures ships canned SUBNETS / GATEWAYS / AGGREGATORS shapes so the demo mode renders the new tabs against believable data.

Widget refactors. A section_title helper de-duplicates panel-title boilerplate across widgets; subnets_with_members is shared between the CLI and the SUBNETS tab so the two views render the same shape.

---

Test hygiene

• Lib suite at 4050+ tests (was 3950+ at v0.21 release). 100+ net new tests across the fold framework (property tests for apply-then-query consistency, TTL expiry determinism, snapshot-restore round-trips, 100K applies/sec stress, concurrent apply + query), the lifecycle layer (add_replica_grows_in_place_preserving_existing_replicas, remove_last_stops_only_the_last_replica, remove_last_refuses_to_drop_below_one, parallel-Vec invariants under spawn_with_placement), the registry service (scale_grows_existing_group_via_template, scale_shrinks_existing_group_to_target, scale_rejects_unknown_group, scale_rejects_template_mismatch, scale_to_same_count_is_noop_and_returns_current_snapshot, scale_to_zero_is_rejected), and the CLI remote-attach surface (cli/tests/aggregator_remote.rs — every verb against an in-process daemon).
• Cross-language wire round-trip pinning. Every binding has a test that pins the canonical error-kind string set + the group_seed-as-hex encoding against the locked wire table. A binding that drifts fails its compatibility test.
• cargo clippy --features meshos,deck,aggregator --all-features --all-targets -- -D warnings clean. The strict floor from v0.20.2 (unwrap_used, expect_used, undocumented_unsafe_blocks, multiple_unsafe_ops_per_block) stays armed; aggregator-side hits caught (manual_is_multiple_of in the HealthMonitor backoff retry-gate).
• cargo doc --features meshos,deck,aggregator --no-deps clean under RUSTDOCFLAGS="-D warnings". Doc-comment hygiene includes rustdoc intra-doc links surfaced under the new warning floor.
• Codecov coverage sits at ~90% on the substrate feature set, informational on the CI status — same posture as v0.21.
• CI pipeline additions. Aggregator-daemon + registry-RPC test job; consumer-side Go wrapper exercised against the cdylib; bindings CI enables the aggregator feature so the surface isn't gated out of the published bindings.

---

Breaking changes

CapabilityIndex removed; callers migrate to Fold<CapabilityFold>

The legacy CapabilityIndex module is deleted. Callers (MeshNode::capability_index, Scheduler::place_*, replica/fork/standby placement, the FFI surface, the Deck capability panel) all moved in the same diff. Consumers reaching into the legacy type directly need to switch to Fold<CapabilityFold> query / snapshot; the inverted-index tag/region/state lookups are part of the fold's Index and surface via CapabilityQuery.

RoutingTable removed; callers migrate to Fold<RoutingFold>

The pingwave-driven RoutingTable is deleted. Router::lookup and MeshNode::dispatch_packet consult the fold instead. Pingwave packets are repurposed as SignedAnnouncement<RouteAnnouncement> on the fold:route: channel — same wire RTT measurement, new envelope.

MeshDaemon is no longer the trait an aggregator-shaped daemon implements

MeshDaemon stays sync-only / WASM-compatible for compute daemons. Async tier services (aggregators today, market matchers / settlement bridges / reputation oracles later) implement the new LifecycleDaemon trait and are deployed via LifecycleGroup<L>. Existing MeshDaemon implementations are unaffected; this is a sibling trait, not a replacement.

net aggregator spawn --source-subnet is gone; --template is required

net aggregator spawn takes --template <NAME> (required) — the template owns the source subnet, summary visibility, fold kinds, and summary interval. --source-subnet was parse-only in v0.21 (the verb errored out before doing anything); no scripted CLI consumer broke, but the help text changed and the flag is removed.

net aggregator scale takes --template <NAME>

Scale needs the operator to re-supply the template name so the server can sanity-check against the group's stored spec (template mismatch → ScaleRejected("template mismatch") before any state change). Same shape as spawn — operators copy the spawn invocation, swap the verb, change the replica count.

RegistryGroupSummary gains source_subnet + fold_kinds

Wire shape additive — postcard appends; existing readers tolerate the additional fields. SDK consumers that rendered the old shape see the new fields populated; constructors that built the struct by hand grow two parameters.

RegistryRequest / RegistryResponse grow a Scale variant

Operators ship CLI + daemon together; no backwards-compatibility constraint. Variant added at the tail; existing match arms compile unchanged.

AggregatorDaemon::on_stop no longer drops mid-publish work

The shutdown-aware tick loop checks the shutdown flag between publishes, and the backstop deadline bumped to absorb realistic publish latencies. Behavior change: an in-flight mesh.publish().await at shutdown now completes (up to the new backstop) instead of being aborted. Consumers that relied on the abort timing (none in the substrate) need to revisit.

AggregatorGroupEntry lives behind AggregatorRegistry::snapshot

Registry inspection goes through AggregatorRegistry::snapshot(), which bundles every field a renderer needs in one lock. Direct field access on AggregatorGroupEntry is no longer the supported path.

aggregator is a default SDK feature

net-sdk ships with the aggregator surface on by default. Consumers who explicitly disabled default features and want the aggregator client get it via --features aggregator; consumers on default features see the new module unconditionally.

---

How to upgrade

1. Rust consumers — update the dependency to 0.22. Most consumers see only the additions. Direct consumers of the legacy CapabilityIndex / RoutingTable need to switch to the fold APIs (the compiler points at every site).

2. Daemon authors with an async daemon — implement LifecycleDaemon, not MeshDaemon. If your daemon does tokio::interval work or await-blocking publish/subscribe, it's a LifecycleDaemon. Deploy via LifecycleGroup<L>::spawn or spawn_with_placement; auto-respawn via register_with_monitor. Existing MeshDaemon impls are unchanged.

3. Operators running aggregators — switch to net-aggregator-daemon. Drop the binary in /usr/local/bin (or your platform's equivalent), write a TOML config with [[template]] blocks (and optionally [[group]] blocks for boot-time instantiation), run net-aggregator-daemon --config foo.toml. Spawn additional groups dynamically via net aggregator spawn --template … --name … --replica-count N --node-addr … --node-pubkey … --node-id …. The bootstrap triple comes from net-aggregator-daemon --config foo.toml --print-bootstrap (first stdout line, JSON).

4. CLI users — adopt --node-addr / --node-pubkey / --node-id or a --remote <NAME> profile. net aggregator query / spawn / scale / ls --remote now round-trips against any daemon you can reach. Set [default].psk_hex + [default].node_addr / node_pubkey / node_id in your CLI config for a one-flag --remote default shortcut.

5. SDK consumers (TypeScript / Python / Go / C) — RegistryClient + FoldQueryClient are first-class. Pull the surface from @net-mesh/sdk / net_mesh.aggregator / net_mesh Go package / the C cdylib's net_registry_client_* symbols. Same wire contract across every language — error kinds, group_seed as 64-char hex, u64 marshaling per the locked table.

6. net aggregator spawn callers — switch to --template. The --source-subnet flag is gone. Templates live in the daemon's TOML; operators reference them by name. --name + --replica-count are unchanged.

7. No CI config change required. The strict clippy floor stays armed; rustdoc warnings stay denied; the test-side allow-list is unchanged. CI adds an aggregator-daemon + registry-RPC test job and enables the aggregator feature on bindings — repo CI picks both up automatically.

8. Operators — bump the binary. Pre-built net-mesh, net-deck, and net-aggregator-daemon binaries land in the release archive for every supported target (Linux x86_64 / aarch64, macOS x86_64 / aarch64, Windows x86_64). Drop in /usr/local/bin and restart. Wire format is additive from v0.21; mixed-version fleets handshake cleanly, though the new fold envelopes and Scale RPC obviously won't reach pre-v0.22 peers.

9. Deck users — three new tabs. SUBNETS, GATEWAYS, and AGGREGATORS appear in the tab strip; the strip scrolls horizontally on overflow. Press Enter on a subnet row to drill into its focus page; cursor + filter on every new table.

Correctness and hygiene patch on top of v0.20. No public API changes, no wire-format changes — drop-in for v0.20.x consumers.

What's in it

Panic-hygiene audit. Library .unwrap() and .expect() calls in production code (src/, excluding #[cfg(test)], integration tests, benches, and examples) are now zero. The audit started from a claim of ~3,090 unwraps and ~853 expects; the actual baseline was 119 and 161. Every remaining call site is either a ? propagation against a real fallible error or an expect("infallible: …") tied to a static guarantee (e.g. <[u8; N]>::try_into on a fixed-size slice).

Lock-poisoning surface removed. Sixteen production files migrated from std::sync::{Mutex, RwLock} to parking_lot::{Mutex, RwLock} — nine in net/, the rest across sdk/, deck/, and the Go/Node/Python bindings. The substrate's lock-holding paths never recovered from poison; parking_lot drops the Result and the poison concept, so the panic-hygiene pass doesn't have to choose between .unwrap() on a PoisonError and propagating an error nothing else handles. A clippy.toml disallowed-methods entry keeps the migration from regressing.

Lint floor. rustfmt.toml and clippy.toml land at net/crates/net/. [lints.clippy] on the net crate warns on unwrap_used, expect_used, undocumented_unsafe_blocks, and multiple_unsafe_ops_per_block. CI splits the clippy job: production code runs strict (--lib --bins -- -D warnings); the test surface allows the four panic-hygiene lints. New unsafe or unwrap in src/ fails CI; the same code in tests/ doesn't.

Unsafe documentation. 195 unsafe blocks across substrate + bindings. The 15 outside the FFI surface already carried per-block SAFETY: comments. The 180 in FFI bridge code share one contract per file, so the eight FFI files (ffi/mod.rs, ffi/mesh.rs, ffi/cortex.rs, ffi/blob.rs, ffi/predicate.rs, ffi/predicate_debug.rs, ffi/schema.rs, ffi/redis_dedup.rs) grow a module-level SAFETY preamble plus a file-level #![expect(undocumented_unsafe_blocks, reason = "…")]. The lint stays armed everywhere else. The audit's static mut and transmute flags didn't match anything in the tree — zero of either.

Codecov telemetry. coverage.yml runs cargo llvm-cov against the full substrate feature set on every push and uploads lcov to Codecov via codecov-action@v6. The job is informational — fail_ci_if_error: false, status checks set to informational in codecov.yml. The first run came back at ~90%; targeted tests close the gaps in transport.rs, proxy.rs, stream.rs, linux.rs, and netdb/db.rs that pinned real behavior. Pure Debug-string and Display-string pins were cut during review — see net/crates/net/docs/TEST_COVERAGE_PLAN.md for the test-worth rule (a test pins behavior a future refactor could plausibly break, not a coverage line count).

Two CI flakes fixed. publish_skips_expired_subscriber_when_sweep_is_disabled had a 1 s TTL racing the handshake on slow runners (bumped to 3 s). meshdb_subprotocol_wire had two inflight_calls() == 0 assertions firing before server-side cleanup drained (replaced with bounded polling loops).

Breaking changes

None.

How to upgrade

Bump the dependency to 0.20.2. No code change required.

Named after Paul Engemann's 1983 anthem from the Scarface soundtrack. v0.18 stood up the operator plane — the TUI cyberdeck, the CLI, and five-language MeshOS / Deck SDKs sitting on top of three releases of substrate. v0.19 pushes the substrate itself past its prior ceilings: nRPC grows client-streaming, server-streaming for client-streamed requests, and full duplex; Dataforts moves from "blob store that paged once" to a terabyte-scale fabric with hierarchical manifests, content-defined chunking, Reed–Solomon erasure coding, durable streaming staging, and per-stream bandwidth classes; the carry-forward bug audit and a five-pass review of the bugfixes branch close 50+ replication / migration / blob / FFI / consumer-loop hazards. And the substrate gets a new name on its packages.

Push past the limits

For three releases the nRPC layer was unary-only. A daemon could call_typed(target, channel, request) and get one response back. Anything that wanted to stream — log tail, snapshot transfer, training-batch upload, multi-shot model inference — either chunked at the application layer and paid the per-chunk round-trip cost, or pinned a request/response pair per chunk and paid the per-call session overhead. v0.19 closes that gap.

For three releases the blob layer was flat. BlobRef::Small for under-a-chunk payloads, BlobRef::Manifest for everything else, with chunk lists serialized in a single u32-bounded array. That topology runs out somewhere around 4 GiB of single-blob payload — past that, the manifest itself stops fitting in a single segment, and a manifest sitting on one node becomes a single point of failure for an arbitrarily-large blob. v0.19 lifts that ceiling too.

v0.19 lands the full nRPC streaming surface — Phase A through Phase F of NRPC_BIDI_STREAMING_PLAN.md — covering wire-format additions (REQUEST_INIT / REQUEST_CHUNK / REQUEST_END / REQUEST_CANCEL plus stream-direction window grants), the substrate RpcStreamingRequestFold server-side handler, the ClientStreamCall<Req, Resp> / DuplexCall<Req, Resp> caller-side surfaces, the SDK-layer Chunk<T> typed wrappers, and the benchmark suite that pins the streaming surface against the unary baseline the nrpc-benchmarks PR established. v0.19 lands Dataforts blob storage v0.3 — BlobRef::Tree (hierarchical manifests with internal/leaf nodes that page through arbitrarily-large blobs without pinning a single-node manifest hotspot), bounded-memory store_stream, durable streaming staging (begin_streaming_store / append_to_stream / finalize_streaming_store / resume_streaming_store so a publisher can crash mid-upload and resume from the last checkpoint without restarting), content-defined chunking (CDC with rolling-hash boundaries — content-aligned dedup across small edits), Reed–Solomon erasure coding (data + parity chunks with stripe-aware GC), per-stream bandwidth classes (Foreground / Background / Realtime), and resume metrics for operator dashboards. v0.19 closes 30+ carry-forward bugs from BUG_AUDIT_2026_05_18_CARRIED_FORWARD.md (R-20 replication peer auth, R-21 leader→replica FSM, X-1 standby epoch fencing, X-9 / X-10 / X-11 / X-18 migration hardening, D-1 / D-11 / D-14 / D-15 blob hardening, O-1 / O-4 / O-5 audit ordering, S-1 / S-2 / S-3 / S-4 subprotocol peer binding, and the long-tail of mediums + lows). And it closes the high-priority items from a five-pass code review of the bugfixes branch (CODE_REVIEW_2026_05_18_BUGFIXES_15.md — C-1 / C-2 silent-state-loss criticals; H-1 through H-8 distributed-consistency hazards on the fixes themselves).

The hardening posture is real work. Five parallel deep-read passes covered the 110 commits / ~98 code files / +7,401 / −1,382 LOC on the bugfixes-15 branch — replication, compute / migration, MeshOS + capability / auth, dataforts + adapters, and FFI / bus / shard / consumer / tests. Each pass flagged items where the fix landed cleanly (verified clean) and items where the fix was itself buggy. The Criticals and Highs land in v0.19 with regression coverage; mediums and lows track on a follow-up sweep doc.

---

Renamed: net → net-mesh

The substrate moves to the net-mesh family across every package registry. Old crate/package names continue to resolve at deprecated-on-publish for one minor version so existing consumers see a build warning before a hard break.

Component	Rust crate	npm	PyPI	Binary
Core lib	net-mesh	@net-mesh/core	net-mesh	—
SDK	net-mesh-sdk	@net-mesh/sdk	net-mesh-sdk	—
CLI	net-cli	@net-mesh/cli	net-mesh-cli	net-mesh
Deck	net-deck	@net-mesh/deck	net-deck	net-deck

The crate-id-as-discriminator name ai2070-net (and the binding equivalents @ai2070/net, ai2070-net, ai2070-net-sdk) was confusing first-time consumers ("is this a tenant-specific fork?") and conflated the org with the substrate. net-mesh is the substrate name; the org owns the registry namespace. Existing consumers: update Cargo.toml from ai2070-net = "0.18" to net-mesh = "0.19", package.json from @ai2070/net to @net-mesh/core, and requirements.txt from ai2070-net to net-mesh. The Go binding's import path stays at github.com/ai-2070/net/go for now — the migration to a net-mesh import path tracks a Go-side breaking-change window.

The CLI binary renames from net to net-mesh so it doesn't shadow /usr/bin/net on some distros. The Deck binary remains net-deck. Both binaries are now published as release artifacts — operators no longer have to cargo install from a workspace member. Pre-built net-mesh and net-deck binaries land in the release archive for Linux x86_64, Linux aarch64, macOS x86_64, macOS aarch64, and Windows x86_64. Distro packages (deb / rpm / Homebrew formula / scoop manifest) ship from CI as the release pipeline matures.

---

nRPC bidirectional streaming

NRPC_BIDI_STREAMING_PLAN.md ships in full — Phases A through F. The new surfaces live in the substrate (adapter::net::cortex::rpc + adapter::net::mesh_rpc) and a typed-veneer layer (net_mesh_sdk::mesh_rpc).

The wire-format additions sit cleanly alongside the existing unary REQUEST / RESPONSE frames. REQUEST_INIT opens a streaming request channel with the chunk-decoder hint; REQUEST_CHUNK carries each input frame with a per-channel monotonic seq; REQUEST_END signals "no more input — the response stream starts now"; REQUEST_CANCEL unwinds in either direction. Request-direction window grants mirror the response-direction grants v0.16 shipped — a sender that fills its window blocks until the receiver acks more credit, so a slow-consumer hot reader can't OOM a fast producer through the in-flight queue. Termination + cancel semantics carry the same trace-context + deadline plumbing the unary path already had. Existing unary call sites compile unchanged; the constants are additive.

The substrate-side fold is RpcStreamingRequestFold. Each in-flight request is keyed on its call_id and carries a per-channel mpsc::Sender<Chunk<RawBytes>>, a deadline timestamp, the trace context, and a CancellationToken. The fold dispatches REQUEST_INIT to the registered handler (which has the channel-typed input + output stream signatures), routes REQUEST_CHUNK / REQUEST_END frames into the per-call sender, and emits the handler's output frames back on the wire as RESPONSE / RESPONSE_END pairs (or RESPONSE_CHUNK / RESPONSE_END for server-streaming responses). Panic / error semantics are: handler Err → wire RESPONSE_ERROR with the structured kind; handler panic → RESPONSE_ERROR { kind: HandlerPanic } + tracing log; cancellation from either side → both directions drop and the receiver gets a typed Cancelled.

Two handler traits land:

#[async_trait]
pub trait RpcClientStreamingHandler {
    type Request: DeserializeOwned;
    type Response: Serialize;

    async fn call(
        &self,
        ctx: RpcContext,
        requests: impl Stream<Item = Result<Self::Request, RpcError>> + Send + Unpin,
    ) -> Result<Self::Response, RpcError>;
}

#[async_trait]
pub trait RpcDuplexHandler {
    type Request: DeserializeOwned;
    type Response: Serialize;
    type OutputStream: Stream<Item = Result<Self::Response, RpcError>> + Send + Unpin;

    async fn call(
        &self,
        ctx: RpcContext,
        requests: impl Stream<Item = Result<Self::Request, RpcError>> + Send + Unpin,
    ) -> Result<Self::OutputStream, RpcError>;
}

The caller-side surfaces are ClientStreamCall<Req, Resp> (many input frames → one response) and DuplexCall<Req, Resp> (many in, stream out). Both expose send(req) for input frames, finish / finish_sending to close the request side, call_id for trace correlation, and a grant_request_window accessor for advanced flow control. DuplexCall::into_split returns a (DuplexSender, DuplexReceiver) pair so the input and output halves can move into separate tasks without contention on a shared handle.

The SDK typed-veneer layer carries the application-friendly shape. RequestStreamTyped<Req> wraps a chunked input stream into Stream<Item = Result<Req, RpcError>>; Chunk<T> is the SDK-internal frame type with Init / Data / End variants the codec dispatches against. The benchmark suite from the nrpc-benchmarks PR extends to cover client-streaming throughput, duplex round-trip latency, and the cancel-mid-stream timing distribution. Phase G — cross-binding parity (Python / Node / Go / C) — defers to a separate plan; the substrate surface ships first, and the bindings catch up in a follow-up release.

---

Dataforts blob storage v0.3

DATAFORTS_BLOB_STORAGE_PLAN_V2.md ships in full — Phases A through D. The blob fabric now scales past the single-manifest ceiling and survives publisher crashes mid-upload without restarting.

BlobRef::Tree is the new wire variant for hierarchical manifests. A small blob still ships as BlobRef::Small { hash, size }. A medium blob still ships as BlobRef::Manifest { encoding, chunks, size }. A large blob ships as BlobRef::Tree { encoding, root_hash, total_size, depth } — the root hash points at a TreeNode::Internal { children: Vec<Hash> } whose children are further internal nodes until the depth hits zero, where leaves carry TreeNode::Leaf { chunks: Vec<ChunkRef> }. The fan-out is configurable per policy; the default (8K chunks per leaf, 4K children per internal) places the cross-over at ~32 GiB before depth-2 fires. Tree manifests page through arbitrarily-large blobs without pinning a single-node hotspot — every internal node has the same replication policy applied as the root, so the fabric self-balances against access pattern.

Bounded-memory store_stream lands as the streaming-publish entry point. A publisher with a Stream<Item = Bytes> no longer materializes the full blob in memory before computing the manifest; store_stream consumes the input incrementally, chunks via the configured strategy, hashes each chunk on the fly, accumulates leaves until the leaf-fanout cap, and emits internal nodes lazily as leaves complete. Memory bound is O(leaf_fanout × chunk_size + depth × internal_fanout × hash_size) — operator-tunable, predictable, and independent of total blob size.

Durable streaming staging is the most operator-visible piece. A long upload that crashes mid-stream used to restart from byte 0; v0.19 lets it resume. The four-step API:

let upload = adapter.begin_streaming_store(config).await?;  // returns StagingHandle
adapter.append_to_stream(&upload, chunk_bytes).await?;       // repeatable
adapter.append_to_stream(&upload, chunk_bytes).await?;       // ...
let blob_ref = adapter.finalize_streaming_store(upload).await?;  // commits
// OR
adapter.abort_streaming_store(upload).await?;                // explicit cancel
// OR — after crash + restart:
let upload = adapter.resume_streaming_store(staging_id).await?;

A StagingCheckpoint { seq, chunking, encoding, completed_leaves, completed_internals, last_chunk_byte_offset, last_checkpoint_unix_ms } persists every N bytes (default 64 MiB) under the staging directory; resume_streaming_store rolls forward to the last checkpoint, replays any uncheckpointed chunks from the publisher's resumed input stream, and continues. Aborted staging directories GC after the configured grace period (default 24 hours).

Streaming + range fetch over BlobRef::Tree ships as fetch_range(blob_ref, range, output_stream). A consumer reading bytes 12_345..67_890 of a 50 GiB tree blob does not fetch the entire tree — the range descends the tree only as deep as needed, fetches the leaf nodes whose chunk ranges intersect, and streams those chunks through to the output. The range path also gets the 32-bit usize::MAX guard from the carry-forward audit (D-2) so a malicious or buggy publisher can't crash a 32-bit consumer with a range that overflows.

Streaming verification runs the hash chain in lock-step with the fetch — each leaf's chunks: Vec<ChunkRef> is verified against the leaf's parent hash before the chunks are surfaced; each internal node's children: Vec<Hash> is verified against the parent's hash before recursing. A tampered hash anywhere in the tree halts the fetch with a typed BlobError::ChainMismatch { at_depth, parent_hash, child_hash }.

Content-defined chunking (CDC) is the new default chunking strategy. Fixed-size chunking still ships as ChunkingStrategy::Fixed { size } for callers who need deterministic chunk boundaries (replication slabs, structured-document stores). ChunkingStrategy::Cdc { avg, min, max } uses a rolling-hash boundary detector — content-aligned chunks dedup across small edits to large blobs (insert a byte at offset 1 GiB in a 10 GiB blob → only the chunks straddling the insertion point change, not every chunk after). Default::default() returns Cdc { avg: 1MiB, min: 256KiB, max: 4MiB }; operators tune via DataGravityPolicy::chunking_strategy.

Reed–Solomon erasure coding lands behind the ChunkRole::{Data, Parity { stripe_index }} tag. A ChunkRef { hash, size, role } now carries its role in the stripe. Tree builders that opt into RS coding (MeshBlobAdapter::store_stream_with_rs(k, n) for n total chunks from k data) emit n-k parity chunks per stripe; the fetch path tolerates up to n-k chunks missing per stripe before erroring. GC + RS interaction invariants are pinned: parity chunks are GC-protected by the same refcount-on-manifest model as data chunks (the manifest references all n chunks; deleting only data without deleting parity leaves an unrecoverable stripe and is now a typed error rather than silent corruption).

Per-stream bandwidth classes carry through the resume path. BandwidthClass::Foreground is the operator-interactive default — full configured bandwidth, prioritized over background traffic. BandwidthClass::Background for cold-tier replication and scheduled backups — throttled when foreground traffic competes. BandwidthClass::Realtime for migration / live replay — bypasses backpressure entirely with a configured emergency reserve. Resume metrics (current_bandwidth_class, bytes_in_class, paused_for_higher_class_ms) surface through the operator dashboard the v0.18 Deck TUI already exposes.

Migration path / wire compat: existing v0.18 BlobRef::Small and BlobRef::Manifest payloads decode unchanged. New BlobRef::Tree payloads are rejected by pre-v0.19 consumers with the existing typed-decode error. Operators publishing tree blobs to a mixed-version fleet should gate the new variant behind a capability tag (dataforts.blob_tree_v3) until the fleet rolls.

---

Carry-forward bug audit

BUG_AUDIT_2026_05_18_CARRIED_FORWARD.md documents the carry-forward audit's five passes (plus a sixth-pass subprotocol sweep and a seventh-pass follow-up). v0.19 closes the Criticals + Highs + a majority of the Mediums. Some highlights of what landed:

• Replication peer authentication. Pre-fix any mesh peer could ship SyncResponse / Heartbeat against a channel they had no role in; the runtime trusted the wire-supplied from_node for both delivery and believed_leader tracking. v0.19 binds replica delivery to a replica_set registered at channel-open time and gates believed_leader updates against the from_node matching a recorded leader claim. A spoofed heartbeat from outside the replica set is now rejected at the dispatch arm.

• Permanent dual-leader resolution. The replication FSM had no Leader → Replica transition — once a node elected itself leader for a channel, it stayed leader until process exit, even after observing a higher-tail-seq leader heartbeat from the rejoining partition. v0.19 adds the transition: a Leader observing another Leader heartbeat with strictly-higher tail (or equal tail + lower node_id as tiebreak) flips to Replica and adopts the other side as its believed_leader. The dual-leader convergence test pins the rule.

• Migration dispatch peer binding. Pre-fix the migration subprotocol arms (SnapshotReady, CleanupComplete, ActivateTarget, MigrationFailed) accepted state-mutating wire input from any session peer; a forged ActivateTarget from a non-orchestrator could force cutover while the source still believed it owned the daemon — divergent chain heads. v0.19 binds each arm to a recorded principal: SnapshotReady checks against source_node, CleanupComplete against source_node, ActivateTarget against orchestrator_node, MigrationFailed against the union of recorded participants. The orchestrator-on-third-party-node topology gets its long-promised wire-shipped target_head in ReplayComplete so the orchestrator no longer falls back to a synthetic parent_hash: 0 that no downstream verifier could reconcile.

• Migration phase-guard hardening. MigrationTargetHandler::replay_events no longer rewinds Cutover → Replay (which had been enabling double-delivery of post-cutover events). MigrationSourceHandler::cleanup gains a phase guard so a pre-cutover replayed CleanupComplete no longer destroys a live daemon. MigrationTargetHandler::pending_events is bounded (64 MiB / 1M events per origin) so a wire-driven OOM is no longer reachable. Source-side buffered_events gains a matching cap; the cap admission bound moves to an O(1) running byte counter on a follow-up sweep.

• StandbyGroup epoch fencing. The local epoch scaffolding lands (term: u64 field bumped on promote / try_recover); cross-node wire enforcement defers to a follow-up wire-protocol bundle. Partial-sync replay filter (X-19) lands alongside.

• Subprotocol from_node binding. The sixth-pass sweep caught three correlation bugs in the rendezvous and membership subprotocols. RendezvousMsg::PunchIntroduce and PunchAck previously correlated on payload-only fields (intro.peer / ack.from_peer) — any session peer could cancel a victim's introduce waiter or hijack an ack. MembershipMsg::Ack correlated on a sequential-counter nonce — predictable nonces let any session peer spoof Subscribe / Unsubscribe responses. v0.19 binds each correlation arm to the wire-authenticated from_node (read from the inbound session, not the payload) and switches membership nonces to getrandom-sourced u64s. nRPC response delivery gets the same binding — a sequential call_id becomes a getrandom u64 and the reply-channel ACL gates response delivery to the originating peer.

• Blob hardening. Sweep D-1 (the GC sweep_gc TOCTOU where a concurrent incr was silently dropped) closes via a remove_if guarded by should_sweep. D-11 adds manifest chunk-size validation + defensive get(..) so an untrusted publisher can't slice-panic the consumer with arbitrary per-chunk sizes. D-14 branches resolve_payload on is_chunked() so the top-level verify skip for manifests no longer unconditionally fails. D-15 makes GC delete_chunk actually unlink the persistent segment file. D-18 fixes a publisher-crafted UTF-8-boundary panic in the FS adapter's URI sanitizer.

• Audit-chain durability ordering. O-4 (chain_append_failures counter + chain record appended BEFORE dispatch — pre-fix the chain record appended AFTER dispatch and a chain-appender failure left an audit gap on a real event). O-5 (record_admin_audit chain append before ring push, ring/chain divergence regression test).

• Substrate-wide ChannelHash widening. ChannelHash widens from u32 to u64. The targeted-collision cost rises from ~2^32 (feasible offline) to ~2^64. The wire NetHeader::channel_hash stays u16 (per the existing u64-canonical / u16-wire / u32-future precedent — fast-path filter hint, may bucket-collide at scale, ACL/storage/config decisions key on the canonical hash via registry disambiguation). The PermissionToken wire form grows to 169 bytes (issuer + subject + scope + 64-bit channel hash + issuer generation + not_before + not_after + delegation depth + nonce + ed25519 signature); the FFI net_channel_hash widens to *mut u64; every binding (Python / Node / Go / C) consumes the JSON channel_hash as int64 / BigInt / uint64 / uint64_t respectively.

The full list lives in the audit doc; the carry-forward sweep covers replication availability (R-25 / R-28 / R-40 priority lane + catchup backoff + NACK retention), replication coordinator state decoupling (R-31 / R-32), replication lows (R-29 / R-30 / R-33 / R-34 / R-35 / R-36 / R-37 / R-38 / R-39), SDK correctness (O-1 UUID epoch + O-2 plumb this_node), MeshOS observability (O-3 / O-7 / O-8), cluster backpressure (O-21 / O-25), maintenance state (O-22 / O-23 / O-24), group lifecycle (X-4 / X-5), compute mediums (X-13 unhealthy-slot recovery + X-16 / X-17 / X-21 / X-22), MeshDB drain (MD-1 / MD-2), blob hardening lows (D-6..D-10 / D-12 / D-13 / D-16), and heat-emission ordering (D-17).

---

Code review — the fixes are themselves clean

The carry-forward audit closed the original bugs. CODE_REVIEW_2026_05_18_BUGFIXES_15.md reviews the fixes themselves — five parallel deep-read passes covering replication, compute / migration, MeshOS + capability / auth, dataforts + adapters, and FFI / bus / shard / consumer / tests. 110 commits, ~98 code files, +7,401 / −1,382 LOC. Where the fix landed cleanly, no entry; where the fix was itself buggy or left a new hazard open, the review flags the item.

v0.19 closes the Criticals and Highs from that review:

• C-1 (MigrationSourceHandler::cleanup unregisters daemon on lookup miss). Pre-fix the new Cutover phase guard ran inside if let Some(entry) = ..., but the migrations.get miss fell through to daemon_registry.unregister(daemon_origin) unconditionally — a spurious or replayed CleanupComplete for an origin we never migrated tore down a live local daemon. Fix: move unregister inside the Some branch; the miss path is now a no-op with a tracing::debug log.

• C-2 (StandbyGroup::try_recover_inner clobbers the active). Pre-fix the unhealthy filter did not exclude self.active_index; if the active was briefly marked unhealthy (transient node heartbeat staleness), recovery constructed a fresh DaemonHost::new with empty state and registry.replaced the live active — silently dropping all committed state and the post-sync buffer. Fix: route active-side unhealthiness through promote, not slot re-placement; the filter excludes the active by construction. ForkGroup / ReplicaGroup were unaffected (no "active" concept) and stay unchanged.

• H-1 (replication dual-leader sticky-tiebreak inconsistency). The runtime convergence tiebreaks on (higher tail_seq, lower node_id); the heartbeat-recording layer tiebroke on lower node_id only and was sticky. A real leader L1 (high tail, high id) could stay Leader while also recording L2 (low tail, low id) as believed_leader. v0.19 unifies on the runtime convergence rule across both layers and pins the regression test.

• H-2 (MigrationTargetHandler::activate flips Cutover before drain_pending). Pre-fix a mid-drain Err left phase already at Cutover; replay_events no-oped, buffer_event rejected, and the undelivered tail was reinserted into pending_events with no future call able to drain it. v0.19 flips Cutover only on successful drain; activate's retry path drains on next call without the early-return.

• H-3 (StandbyGroup try_recover_inner does not bump term). The X-1 fencing gap that ForkGroup and ReplicaGroup already guarded against was open on StandbyGroup. v0.19 bumps term in try_recover to match promote / promote_with_placement.

• H-4 (PollMerger::poll discards set_checked bool). Both Step-1 (adapter next_id) and Step-2 (last-event override) writes routed through set_checked but ignored the bool return. On a format-mismatch refusal, fetched events were still returned in all_events, but the cursor was not advanced — the caller next-polled with the same cursor, got identical events, and entered an infinite duplicate-delivery loop. v0.19 drops the offending shard's events on refusal and marks the shard in failed_shards.

• H-5 (SnapshotReady TOFU into orchestrator binding). For a daemon_origin with no prior record, restore_on_target ran and target_handler.orchestrator_node was recorded as from_node — any session peer that beat the legitimate orchestrator with a forged SnapshotReady became the bound orchestrator and could drive ActivateTarget / MigrationFailed past the new peer-auth gates. v0.19 closes the TOFU window with DaemonFactoryRegistry::bind_expected_orchestrator — operators who know the orchestrator out-of-band can pre-bind it at factory-install time; when bound, a mismatching sender is rejected at the dispatch arm before restore_on_target records anything.

• H-6 (D-1 sweep can orphan on-disk chunks). The fix dropped the refcount entry before close_and_unlink_file; on a close failure the refcount was gone and no future GC sweep could find the orphan. v0.19 reverses the order — close first, then refcount.remove only on success — and adds a disk-inventory orphan-sweep follow-up as a tracked enhancement.

• H-7 (empty-response backoff misfires on stale leader_tail). The backoff recorded "empty" whenever new_tail == pre_apply_tail && leader_tail > new_tail, but leader_tail was the cached value from the last received heartbeat. v0.19 keys backoff on the response's leader_first_retained_seq / leader-tip hint, only counting empties when the request explicitly asked above tail.

• H-8 (record_tail_seq from on_tick advertises pre-quorum tail). The leader was bumping tail_provider the moment a local write landed (pre-quorum), and advertising that via capability tags + the dual-leader tiebreak rule biased future elections toward the partition with un-replicated writes. v0.19 advertises the quorum-confirmed tail (last_quorum_tail) instead, and the leader's pre-quorum tail surfaces only through the per-replica pending_apply metric.

The Mediums and Lows from the review track on a follow-up cleanup sweep (BUG_AUDIT_2026_05_25_CARRYFWD.md); none of them open immediate-blast-radius hazards but several are observable in production over time (M-3 password leak on unencoded @, M-4 duplicate emissions on concurrent tick, M-7 sentinel loopback fallback, M-9 budget-refund-on-Ok, M-10 / M-11 token leak on role flip).

---

Test hygiene

• Lib suite at 3700+ tests (was 3115+ at v0.18 release). 500+ net new tests across the nRPC streaming server fold + client streaming + duplex surfaces, the Dataforts tree manifest + staging + CDC + RS coding paths, the carry-forward audit regression coverage (peer-auth gates, phase guards, audit ordering, channel-hash widening), and the review-driven regressions for C-1 / C-2 / H-1 through H-8.
• cargo clippy --features meshos,deck --all-features --all-targets -- -D warnings clean across substrate + every binding crate + the deck demo + the deck TUI + the net-mesh CLI.
• cargo doc --features meshos,deck --no-deps clean under RUSTDOCFLAGS="-D warnings" — every public item in the v0.19 surface carries a doc comment; intra-doc links resolve through the public re-exports.
• CI matrix expanded. The Rust step now builds with the nrpc-streaming and dataforts-tree features in addition to the default set so the new surfaces compile on every PR. Python / Node / Go / C bindings pick up the ChannelHash u32 → u64 widening regression suite — every binding's channel_hash round-trip + token-parse path runs on every CI build.
• Code-review regression suite. tests/review_2026_05_18_*.rs covers each Critical and High from the bugfixes-15 review with a regression that would have failed pre-fix and passes post-fix. The naming convention pins the review-pass provenance so future regressions trip an obvious tag.

---

Breaking changes

Crate / package renames

ai2070-net → net-mesh. @ai2070/net → @net-mesh/core. ai2070-net-sdk (PyPI) → net-mesh-sdk. Old names continue to publish at deprecated-on-resolve for one minor version; consumers see a build warning before a hard break in v0.20. Update your Cargo.toml / package.json / requirements.txt accordingly.

CLI binary rename

net → net-mesh. Operator scripts referencing /usr/local/bin/net should update to net-mesh. Distro packages and tab-completion shims pick up the new name automatically.

PermissionToken wire format

Token wire size grows from 161 bytes to 169 bytes. The added bytes are the issuer-generation u32 (already in the signed payload after the v0.17 revocation-registry change) and the channel-hash widening (u32 → u64 — was 4 bytes, now 8). Pre-v0.19 tokens are rejected on decode; reissue tokens to clients. The signed-payload field shifts mean old signatures don't verify against the new layout — there is no in-place upgrade.

MigrationMessage::ReplayComplete wire format

ReplayComplete now carries a target_head: CausalLink (32 bytes) so a third-party orchestrator (a node that is neither source nor target) can stamp a verifiable continuity-proof anchor without consulting its local daemon registry. Pre-v0.19 ReplayComplete payloads (40 bytes) are rejected on decode; v0.19 payloads are 72 bytes. The new field is mandatory; the target node fetches it from the freshly-replayed daemon's head_link() before sending.

BlobRef::Tree wire variant

New variant on BlobRef. Pre-v0.19 decoders reject the variant with a typed error. Operators publishing tree blobs to a mixed-version fleet should gate the variant behind a capability tag (dataforts.blob_tree_v3) until the fleet rolls.

nRPC dispatch constants

New wire-level constants for the streaming surface: REQUEST_INIT = 0x10, REQUEST_CHUNK = 0x11, REQUEST_END = 0x12, REQUEST_CANCEL = 0x13, plus REQUEST-direction WINDOW_GRANT mirror. Pre-v0.19 dispatchers reject the constants with a typed "unknown dispatch" error. Existing unary callers are unaffected.

MigrationOrchestrator::on_replay_complete signature

The orchestrator's on_replay_complete(daemon_origin, replayed_seq) becomes on_replay_complete(daemon_origin, replayed_seq, target_head: CausalLink). The new parameter is the wire-shipped target head; the function is pure (no implicit local-registry dependency). Callers using the dispatcher path (MigrationSubprotocolHandler) pick up the new arg automatically; direct orchestrator callers (tests, integration harnesses) update by passing the daemon's head_link or a synthetic test link.

---

How to upgrade

1. Rename your dependencies. Cargo.toml: ai2070-net = "0.18" → net-mesh = "0.19". package.json: @ai2070/net → @net-mesh/core. requirements.txt: ai2070-net → net-mesh. The old names continue to resolve in v0.19 with a deprecation warning; in v0.20 they hard-break.

2. Reissue tokens. v0.18 tokens (161 bytes) fail decode on v0.19 (which expects 169). Run your token-mint pipeline against the v0.19 SDK and propagate the new tokens to every client. Short-TTL tokens roll naturally; long-TTL tokens require an explicit reissue pass.

3. Operators — install the binary. v0.19 ships pre-built net-mesh and net-deck binaries for every supported target. Download from the release archive (Linux x86_64 / aarch64, macOS x86_64 / aarch64, Windows x86_64), drop in /usr/local/bin (or your platform's equivalent), and run net-mesh --help. The Cargo install path (cargo install --path cli) still works from a workspace checkout. Generate an operator identity with net-mesh identity generate <name> and install the public key into the cluster's operator registry as before.

4. nRPC client-streaming callers. let mut call = mesh_rpc.call_client_streaming::<Req, Resp>(target, channel).await?; returns a ClientStreamCall<Req, Resp>. Call call.send(req).await? per input frame, call.finish().await? to close the request side. The single response comes back from finish. Pass a tracing context via the existing RpcContext::with_trace builder if needed.

5. nRPC duplex callers. let call = mesh_rpc.call_duplex::<Req, Resp>(target, channel).await?; returns a DuplexCall<Req, Resp> implementing Stream<Item = Result<Resp, RpcError>>. Call call.send(req).await? for input, call.finish_sending().await? to close the request side, poll the stream side via .next().await for responses. call.into_split() returns a (DuplexSender, DuplexReceiver) pair for tasks that need the halves separately.

6. Streaming blob publishers. Long uploads benefit from the new staging API. let upload = adapter.begin_streaming_store(config).await?; → loop adapter.append_to_stream(&upload, chunk).await?; → let blob_ref = adapter.finalize_streaming_store(upload).await?;. On crash, let upload = adapter.resume_streaming_store(staging_id).await?; rolls forward to the last checkpoint. The StagingHandle::staging_id() accessor returns a stable id you can persist alongside your upload-tracking record.

7. Tree blob consumers. No code change — MeshBlobAdapter::fetch_range(blob_ref, range, output) handles Small / Manifest / Tree transparently. Mixed-version fleets where some nodes are still v0.18 should gate Tree publishes behind a dataforts.blob_tree_v3 capability tag; v0.18 consumers will reject the variant.

8. Reed–Solomon erasure coding. Opt in via MeshBlobAdapter::store_stream_with_rs(input, k_data_chunks_per_stripe, n_total_chunks_per_stripe, config). The fetch path tolerates up to n-k chunks missing per stripe before erroring. GC observes the role-aware refcount model — parity chunks are GC-protected by the same refcount-on-manifest as data chunks.

9. Bandwidth classes. Tag a stream at open: BlobStoreConfig::default().with_bandwidth_class(BandwidthClass::Background) for cold-tier replication; Realtime for migration / live replay. The default is Foreground (operator-interactive). Operator dashboards surface current_bandwidth_class / bytes_in_class / paused_for_higher_class_ms per stream.

10. Migration orchestrator on a third node. No code change for SDK consumers — the wire format change ships under the hood. Direct MigrationOrchestrator::on_replay_complete callers in test harnesses update their call sites to pass a third target_head: CausalLink argument; use the daemon's head_link() if registered locally, or CausalLink::genesis(origin, 0) for snapshot-only test cases.

11. Replication FSM Leader → Replica. No call-site change — the runtime handles the transition internally when it observes a higher-tail-seq leader heartbeat from a recovering partition. Operators monitoring believed_leader_changes see the additional flip count under partition-heal scenarios.

12. Subprotocol peer binding. No code change for SDK consumers — the peer-auth gates ship under the hood. Operators monitoring the subprotocol_peer_auth_rejections counter see legitimate-zero in steady state and non-zero only under attack or misconfiguration; alarm on sustained non-zero.

Named after Steve Stevens's 1989 solo album — same guitarist as v0.15's Rebel Yell, next chapter. v0.15 made the Dataforts data plane stand up. v0.16 stacked the MeshDB query plane on top. v0.17 stacks the MeshOS behavior plane on both: a per-node event loop + reconcile + admit + dispatch + scheduler + chain integration that composes against the capability index, proximity graph, replication election, daemon registry, migration orchestrator, and MeshDB snapshot fold the prior releases shipped.

MeshOS

MeshOS is the cluster-behavior engine that turns the Net substrate into a living distributed operating system, and v0.17 is where it lands. The substrate before MeshOS shipped every primitive a cluster needs — replicas placed by PlacementFilter, chains advertised through the capability index, blobs moved by Dataforts, queries answered by MeshDB, sessions cryptographically pinned by Net — but every primitive ran as its own independent reactor. The replication coordinator spawned per-channel heartbeat tasks. The CortEX adapter folded events wherever a consumer asked. The migration orchestrator handled handoffs but was wired by hand. Each reactor was correct in isolation; nothing wired them into a single coherent observation of what the node is doing right now.

MeshOS is that single observation point. One canonical event loop per node consumes the union of seven event types — replica updates, daemon lifecycle signals, RTT samples, node health flips, admin actions, blob announcements, placement intent — folds them into a MeshOsState view, compares against the DesiredState Dataforts continuously emits, and produces a minimal action list per tick: StartDaemon / StopDaemon / PullReplica / DropReplica / RequestPlacement / RequestEviction / MigrateBlob / MarkAvoid / ApplyBackoff / CommitMaintenanceTransition. Actions ride through a single admission gate (admit()) that funnels every outbound act through one coherent backpressure layer — global pull cooldown, drain rate-limit, per-daemon crash-loop gating, per-chain replica stabilization windows, cluster-wide hysteresis flag — and dispatch to a pluggable ActionDispatcher that bridges to the existing subsystems. The substrate stays unchanged; MeshOS composes against it.

The behavior layer is what makes the cluster move. Daemons that crash get exponential backoff, then a crash-loop gate at five failures per minute. Replicas that under-score relative to a PlacementFilter-driven PlacementScorer get evicted by the chain's elected leader and refilled on the next reconcile pass — same primitive, applied as a feedback loop. RTT samples cross a 250 ms degradation threshold and become avoid-list entries; the leader's continuous-rebalance scoring loop reads them. Admin events ride RedEX chain commits — EnterMaintenance, Drain, Cordon, DropReplicas, ClearAvoidList, InvalidatePlacement — so every node converges on the same operator-driven view without RPC coordination. The maintenance state machine (Active → EnteringMaintenance → Maintenance → ExitingMaintenance → Recovery, with DrainFailed as the deadline-elapsed sideways arc) is per-node and chain-driven; every transition is idempotent under replay.

The supervisor surface that daemons see is small and disciplined. MeshDaemon gains three optional methods with default impls — health() -> DaemonHealth, saturation() -> f32, on_control(DaemonControl) — so every existing daemon compiles unchanged while new daemons can participate in graceful shutdown, drain coordination, and cluster-wide backpressure. The control surface is the WASM-friendly DaemonControl enum carrying relative-millisecond deadlines (the loop-internal MeshOsControl keeps Instant-anchored deadlines for scheduling and bridges via to_daemon_control(now)). Variants cover the full operational range — Shutdown { grace_period_ms }, DrainStart { grace_period_ms }, DrainFinish, BackpressureOn { level }, BackpressureOff — and arrive through the canonical control channel the supervisor owns.

Observability folds back through the same model the rest of the substrate uses. The behavior snapshot — daemons (lifecycle, health, saturation, restart-state), replicas (holders, desired count, elected leader), peers (RTT, health, maintenance-mirror), the local avoid list, the node's own maintenance state, pending actions, and a bounded recent_failures ring buffer — is a MeshOsSnapshot published live behind an ArcSwap<MeshOsSnapshot> (lock-free reads from any thread) and committed durably through an ActionChainAppender whose records ride a RedEX chain. MeshOsSnapshotFold (impl RedexFold<MeshOsSnapshot>) consumes those records on every node, so Deck queries a per-node folded snapshot through MeshDB's MeshQuery::Latest against the snapshot chain — no new wire protocol, no separate observability stack. The federated query plane v0.16 shipped becomes the cluster-jungle render surface v0.17 promises.

There is no separate orchestration service to provision. There is no scheduler daemon to deploy. The reconciliation loop is on the mesh because the substrate is the cluster.

---

v0.17 lands the full MeshOS substrate behind the meshos Cargo feature — the canonical event loop, the desired-vs-actual reconcile, daemon supervision (BackoffTracker with crash-loop gating + the MeshDaemon trait extension + graceful-shutdown plumbing), replica enforcement (leader-only Request* emission + per-node LocalReplicaIntent projection of admin events), locality awareness (RTT-driven MarkAvoid emission + pull-via-tick proximity / health probes), admin events (chain-driven EnterMaintenance / ExitMaintenance / Drain / Cordon / DropReplicas / ClearAvoidList / InvalidatePlacement), the maintenance state machine (chain-driven transitions with per-state metadata), the behavior snapshot (ArcSwap-published per-tick build + RedexFold<MeshOsSnapshot> over the action chain), the single admit() backpressure layer (pull cooldown / replica stabilization / drain rate-limit / cluster hysteresis), the action executor (admit → dispatch → retry-through-admit → record-to-chain), the continuous-rebalance scoring loop (per-chain leader-driven eviction emission gated on score_floor + hysteresis_gap + cooldown), and the action chain integration (postcard-versioned ActionChainRecord + ActionChainAppender trait + MeshOsSnapshotFold that updates recent_failures from the chain replay). Two source-converter patterns ship in lockstep: push-via-observer for the DaemonRegistry and ReplicationCoordinator (low-latency lifecycle / replica-transition events) and pull-via-tick for the proximity graph (RTT samples + health classifications via LocalityProbe + HealthProbe traits, with the [u8; 32] ↔ u64 id-bridge pinned to the substrate's mesh::graph_id_to_node_id convention). The full surface ships behind MeshOsRuntime::start(config, dispatcher) — one call replaces the hand-wired loop + executor + handle + reader + scheduler + probes wiring every consumer would otherwise re-implement.

The hardening posture from the Black Diamond / Rebel Yell / Eye of the Tiger line continues. Two coordinated code-review passes landed before the v0.17 branch cut, covering the async stitching layer, the pure-sync decision logic, the backpressure / dispatch / chain integration, and the SDK plan + README in one combined punch list — 8 Criticals, 23 Importants, 16 Nits across the two passes. Every item closed in-tree with per-item regression coverage where the shape made one possible. The list is real work: the dispatch retry path no longer bypasses admit (transient errors used to drift cooldown counters permanently); the cluster-backpressure broadcast is wired into the executor (update_cluster_backpressure was unit-tested but disconnected at runtime); the scheduler's eviction emission is idempotent under double-reconcile (a pending_evictions: HashSet<ChainId> written by the loop and cleared on observed holder-count drop); reconcile drops on a full action queue are counted + surfaced through RuntimeStats instead of silent let _ = try_send(...); the snapshot publish path is genuinely lock-free (ArcSwap<MeshOsSnapshot> replacing the prior parking_lot::RwLock<Arc<MeshOsSnapshot>>); ApplyBackoff no longer re-emits every tick while a daemon is BackingOff (a last_applied_backoff sentinel on MeshOsState); Phase C and the scheduler arm can no longer double-evict the same chain on the same tick; the fold side now anchors every Instant::now() on the loop's last_tick for replay determinism; MeshOsState::replicas is a BTreeSet<NodeId> rather than Vec<NodeId> so reconcile is O(N log N) across many chains; MeshOsRuntime has a Drop impl that aborts both tasks (no more leak when a consumer forgets shutdown()); probe and dispatcher panics are caught with std::panic::catch_unwind and recorded as FailureRecords rather than killing the loop or executor task; the defer heap enforces a max_defer_count (default 16) before dropping a poison-pill action; MissedTickBehavior::Delay replaces Skip so a slow tick doesn't silently lose reconcile passes; BufferingActionChainAppender is bounded with drop-oldest semantics; ActionChainRecord carries a one-byte wire-format version that the decoder checks before postcard dispatch; MeshOsHandle::publish_timeout(event, Duration) lands so source converters with a wedged loop don't park indefinitely; FailureRecord.age_ms derives from emitted_at_ms at snapshot-read time rather than the misleading constant zero; tracing instrumentation lands across every loop entry / shutdown / panic / dropped action / probe install; Instant + Duration arithmetic uses checked_add everywhere; ReplicaTransitionEvent::LeaderLost fires on Leader → {Replica, Idle} so MeshOsState::replica_leader clears properly; MeshOsLoop::new returns a MeshOsLoopParts struct rather than a 4-tuple so adding a probe registry or stats handle later isn't a breaking change; probe_counts() reads both lengths under a single guard; MeshOsSnapshot::from_state now populates recent_failures from MeshOsState::recent_failures (previously hard-coded empty); MeshOsRuntime exposes register_daemon(...) so the trait-implementor SDK path doesn't have to reach into the runtime's internals; the snapshot's pending field is correctly named after what it carries (recently-emitted-but-not-yet-acknowledged actions); CommitMaintenanceTransition { target: DrainFailed } now carries a reason field; public Config structs gain #[non_exhaustive]; the BackpressureState::release_failed_admit rollback fix replaces a wrong-entry pop-by-equality bug; the replica step-down path emits a single committed event rather than two events that could fragment under back-pressure; run_reconcile samples Instant::now() once per tick rather than three times. 172 meshos unit tests + 11 pipeline integration tests + 13 daemon-registry + 9 daemon-trait + 15 replication-coordinator tests all pass. cargo clippy --features meshos --lib --tests -- -D warnings clean. RUSTDOCFLAGS="-D warnings" cargo doc --features meshos --no-deps --lib clean.

The MeshOS SDK plan covering Rust / Python / Node / Go / C ships alongside as a design document — MESHOS_SDK_PLAN.md. The Rust SDK is the canonical surface; Python / Node / Go / C land in dependency order per consumer demand, all gated on the daemon-side-only restriction (no placement APIs, no admin-event issuance, no MeshOS-control surfaces in any binding, ever). A new sdk workspace member at crates/net/sdk/ opens the slot.

No new dependencies. No protocol changes. The crate version moves from 0.16.x to 0.17.0 to reflect the new feature surface; the workspace gains the sdk member.

---

The canonical event loop

The single per-node event loop that everything composes against. Lives in src/adapter/net/behavior/meshos/event_loop.rs.

pub struct MeshOsLoop { /* ... */ }
pub struct MeshOsLoopParts {
    pub loop_: MeshOsLoop,
    pub handle: MeshOsHandle,
    pub actions_rx: mpsc::Receiver<PendingAction>,
    pub snapshot_reader: MeshOsSnapshotReader,
}

impl MeshOsLoop {
    pub fn new(config: MeshOsConfig) -> MeshOsLoopParts { ... }
    pub fn with_probe_registry(self, registry: ProbeRegistry) -> Self { ... }
    pub fn with_scheduler_registry(self, registry: SchedulerRegistry) -> Self { ... }
    pub async fn run(self) -> u64 { ... }
}

pub enum MeshOsEvent {
    Tick,
    ReplicaUpdate(ReplicaUpdate),
    DaemonLifecycle { daemon: DaemonRef, signal: DaemonLifecycleSignal },
    RttSample { peer: NodeId, rtt: Duration },
    NodeHealth { peer: NodeId, health: NodeHealth },
    AdminEvent(AdminEvent),
    BlobAnnouncement(BlobAnnouncement),
    PlacementIntent(PlacementIntent),
    DaemonIntentUpdate(DaemonIntentUpdate),
    LocalReplicaIntent(LocalReplicaIntentUpdate),
    ReplicaLeaderUpdate { chain: ChainId, leader: Option<NodeId> },
    MaintenanceTransitionObserved { node: NodeId, state: MaintenanceState },
    Shutdown,
}

One mpsc receiver, one heartbeat-aligned tick timer (default 500 ms, MissedTickBehavior::Delay), one reconcile pass per tick. Every source converts to a MeshOsEvent and publishes through MeshOsHandle; reconcile runs (actual, desired, this_node, locality, maintenance, scheduler, scorer) -> Vec<MeshOsAction> as a pure-sync function, idempotent under replay. Actions land on actions_tx (drop-and-count on overflow, surfaced via RuntimeStats.dropped_actions); the action executor drains. The snapshot publishes through ArcSwap<MeshOsSnapshot> after every reconcile pass.

MeshOsLoopParts replaces the prior 4-tuple constructor — adding a probe registry or stats handle in a future slice no longer requires a breaking change to callers.

---

Daemon supervision

The MeshDaemon trait gains three optional methods with default impls:

pub trait MeshDaemon: Send + Sync {
    /* existing required: name / requirements / process / snapshot / restore */

    fn health(&self) -> DaemonHealth { DaemonHealth::Healthy }
    fn saturation(&self) -> f32 { 0.0 }
    fn on_control(&mut self, _event: DaemonControl) {}
}

pub enum DaemonHealth { Healthy, Degraded { reason: String }, Unhealthy }

pub enum DaemonControl {
    Shutdown { grace_period_ms: u64 },
    DrainStart { grace_period_ms: u64 },
    DrainFinish,
    BackpressureOn { level: f32 },
    BackpressureOff,
}

Defaults preserve source compatibility for every existing daemon. DaemonHealth lives in compute::daemon as the canonical type; MeshOS re-exports it. DaemonControl carries WASM-friendly relative-millisecond deadlines so daemons running in any clock domain can react.

The supervisor side runs in behavior::meshos::supervision. Per-daemon BackoffTracker records crash timestamps in a rolling window, advances RestartState through Idle → BackingOff { until } → BackingOff { until } (window doubles per crash up to 60 s cap) → CrashLooping { until } after five crashes within 60 s. A "stable run" (longer than stable_run_threshold, default 60 s) resets the window back to initial. The gate state is observable as RestartState::is_admissible(now); reconcile reads it to decide whether StartDaemon is admissible. ApplyBackoff { daemon, until } records the gate until on the snapshot fold when a desired-Run daemon is currently gated — and now only re-emits when the until actually changes, not every tick.

StopDaemon emits with a 30 s grace deadline (STOP_GRACE_PERIOD). The supervisor sends MeshOsControl::Shutdown { deadline } and waits; past the deadline the supervisor force-terminates. Both StopDaemon and ApplyBackoff carry relative-ms deadlines on the wire — Instant-anchored values stay loop-internal.

A new DaemonLifecycleObserver trait on compute::daemon lets the DaemonRegistry's register / replace / unregister paths fire lifecycle events through MeshOsDaemonLifecycleSink into the loop. attach_to_daemon_registry(registry, handle) is the one-line wiring helper.

---

Replica enforcement

Two arms per the canonical leader/follower split:

pub enum MeshOsAction {
    /* … */
    PullReplica { chain: ChainId, source: NodeId },
    DropReplica { chain: ChainId },
    RequestPlacement { chain: ChainId, exclude: Vec<NodeId> },
    RequestEviction { chain: ChainId, victim: NodeId },
    /* … */
}

Per-node intent (any node). DesiredState::desired_local_replicas carries a per-chain Hold / Drop projection from the leader's RequestPlacement / RequestEviction decisions. Reconcile emits PullReplica { chain, source = lex-smallest other holder } when the local intent is Hold and this node isn't already a holder; DropReplica when the local intent is Drop and this node currently holds.

Cluster-wide count (leader-only). Reconcile reads MeshOsState::replica_leader[chain] and emits RequestPlacement / RequestEviction only when this node is the elected leader. Naive victim selection picks the lex-smallest holder; the continuous-rebalance scheduler refines this with placement-score ranking. A pending_evictions: HashSet<ChainId> written by the loop on emission and cleared when the fold observes the holder-count drop gates the scheduler arm so double-reconcile within one cooldown window doesn't pile on duplicate evictions.

MeshOsState::replicas is a BTreeSet<NodeId> keyed by chain — the deterministic-iteration property the lex-smallest selection relies on is preserved while the set membership / iteration costs are O(N log N) instead of Vec's O(N²).

A new ReplicaTransitionObserver trait on redex::replication_coordinator fires BecameHolder / Idled / LeaderChanged / LeaderLost events from the coordinator's transition_to success path. MeshOsReplicaTransitionSink translates each to the matching MeshOsEvent (with LeaderLost → ReplicaLeaderUpdate { leader: None } so replica_leader clears properly when the elected leader steps down). attach_to_replication_coordinator(coord, handle, this_node) wires per-channel.

---

Locality + admin events

pub enum AdminEvent {
    EnterMaintenance { node: NodeId, deadline: Option<Instant> },
    ExitMaintenance { node: NodeId },
    Drain { node: NodeId, deadline: Instant },
    Cordon { node: NodeId },
    Uncordon { node: NodeId },
    RestartAllDaemons { node: NodeId },
    ClearAvoidList { node: NodeId },
    DropReplicas { node: NodeId, chains: Vec<ChainId> },
    InvalidatePlacement { node: NodeId },
}

RTT samples above LocalityConfig::degraded_rtt_threshold (default 250 ms, 2× heartbeat cadence) emit MarkAvoid { peer, reason, ttl }. Gated on whether the peer is already in MeshOsState::avoid_list so a persistently-bad peer produces one action, not one per tick. Emission sorts by peer id for byte-stable output. Avoid-list entries expire after avoid_ttl (default 5 min); the per-Tick fold GCs expired entries.

DropReplicas { node, chains } projects into DesiredState::desired_local_replicas[chain] = Drop for the named chains when node == this_node. The same DropReplica emission path the leader-driven scheduler uses handles the actual action — operator-commanded drops and scheduler-driven drops share one code path. ClearAvoidList empties MeshOsState::avoid_list in the fold; subsequent reconcile passes re-evaluate RTT and re-emit MarkAvoid if the underlying RTT is still bad.

Admin commits are signed via the existing channel-auth guards (CHANNEL_AUTH_GUARD_PLAN.md); unauthorized commits are rejected at the chain-commit layer and never reach the reconcile pass. The fold consumes them identically on every node, so two operators racing each other resolve at the chain-commit ordering rather than via RPC coordination.

---

Pull-via-tick probes — proximity + heartbeat

Two pluggable probe traits:

pub trait LocalityProbe: Send + Sync + 'static {
    fn rtt_samples(&self) -> Vec<(NodeId, Duration)>;
}

pub trait HealthProbe: Send + Sync + 'static {
    fn health_samples(&self) -> Vec<(NodeId, NodeHealth)>;
}

Polled by the loop on every Tick, BEFORE reconcile, so the freshest fold drives the diff. The cadence-bound poll coalesces what would otherwise be a per-pingwave observer firing on the hot path — proximity-graph edge updates run many per second per peer, but reconcile only needs the latest sample per tick.

ProximityGraphLocalityProbe reads RTT from ProximityGraph::all_nodes(). ProximityGraphHealthProbe derives Healthy / Degraded / Unreachable from ProximityNode::last_seen against thresholds (defaults 1.5 s degraded, 5 s stale — 3× and 10× heartbeat). The [u8; 32] ↔ u64 id-bridge follows the substrate's mesh::graph_id_to_node_id convention (first 8 bytes little-endian) — pinned at the SDK boundary so MeshOS's u64 NodeId and the proximity graph's 32-byte form interoperate cleanly.

ProbeRegistry is a clone-shared cell (Arc<RwLock<Vec<...>>>) so consumers can install probes after MeshOsRuntime::start — the runtime retains its registry clone; the loop reads through; additions take effect on the next Tick. Each registered probe is wrapped in std::panic::catch_unwind; a panicking probe records a FailureRecord rather than killing the loop task.

---

Maintenance state machine

Per-node state machine driven by chain-committed admin events and condition-driven forward transitions:

pub enum MaintenanceState {
    Active,
    EnteringMaintenance { since: Instant, deadline: Option<Instant> },
    Maintenance { since: Instant },
    ExitingMaintenance { since: Instant },
    DrainFailed { since: Instant, reason: String },
    Recovery { since: Instant },
}

AdminEvent::EnterMaintenance { node, deadline } flips local_maintenance to EnteringMaintenance when node == this_node. Reconcile observes the conditions on every Tick: when all local replicas have migrated AND all daemons are stopped, emit CommitMaintenanceTransition { target: Maintenance }. When the deadline elapses with conditions unmet, emit CommitMaintenanceTransition { target: DrainFailed { reason } } — the reason rides on the wire so the operator surfacing on Deck carries the actual failure mode, not a generic flag. AdminEvent::ExitMaintenance flips from Maintenance (or DrainFailed) to ExitingMaintenance; reconcile observes daemon-restart health and emits Recovery once all daemons are running healthy. The Recovery ramp-up window (default 5 min via MaintenanceConfig::recovery_ramp_window) ends with a CommitMaintenanceTransition { target: Active }.

The transition round-trip through the chain lands via MeshOsEvent::MaintenanceTransitionObserved { node, state } — the action executor commits, the chain replay surfaces it, the fold gates the local state advance on whether the prior state was a valid predecessor. since is anchored on last_tick so two replays of the same admin-event sequence produce identical state.

CommitMaintenanceTransition's target enum carries the reason: String field for DrainFailed directly — no out-of-band metadata required.

---

Behavior snapshot fold for Deck

The serializable projection of every loop's view, published live behind ArcSwap<MeshOsSnapshot>:

pub struct MeshOsSnapshot {
    pub daemons: BTreeMap<u64, DaemonSnapshot>,
    pub replicas: BTreeMap<ChainId, ReplicaSnapshot>,
    pub peers: BTreeMap<NodeId, PeerSnapshot>,
    pub avoid_list: BTreeMap<NodeId, AvoidEntrySnapshot>,
    pub local_maintenance: MaintenanceStateSnapshot,
    pub recently_emitted: Vec<PendingActionSnapshot>,
    pub recent_failures: VecDeque<FailureRecord>,
}

All fields Serialize + Deserialize; Instant is flattened to milliseconds-relative-to-snapshot for wire portability. Tests pin postcard + JSON round-trip across every variant; the wire shape is part of the public API once Deck integrates. FailureRecord.age_ms derives at snapshot-build time from the record's emitted_at_ms (previously hard-coded zero — the field is now meaningful, not just stable).

recently_emitted is the ring buffer of actions reconcile has emitted but the executor hasn't acknowledged; bounded by action_queue_capacity. recent_failures collects entries from three sources: dispatcher errors (with retry_after_ms if any), admit-time gate trips (with cooldown_ms if any), and probe / dispatcher panic catches. MeshOsSnapshot::from_state(actual, desired, recently_emitted) builds the projection on demand; the loop publishes after every reconcile.

MeshOsSnapshotReader::read() clones the Arc<MeshOsSnapshot> under a single ArcSwap::load_full — no read lock, no contention with the publisher.

A MeshOsSnapshotFold (impl RedexFold<MeshOsSnapshot>) consumes ActionChainRecords and updates a per-node snapshot on chain replay:

pub struct ActionChainRecord {
    pub id: u64,
    pub kind: String,
    pub emitted_at_ms: u64,
    pub disposition: ActionDisposition,
}

pub enum ActionDisposition {
    Dispatched,
    Failed { reason: String, retry_after_ms: Option<u64> },
    Gated { reason: String, cooldown_ms: Option<u64> },
}

Dispatched records leave the fold silent (the recently-emitted ring covers them); Failed and Gated records push FailureRecords onto recent_failures, bounded by RECENT_FAILURES_CAPACITY = 256. The record carries a one-byte wire-format version that the decoder checks before postcard dispatch; an older / newer record surfaces as DecodeError::UnsupportedVersion rather than garbled deserialization. BufferingActionChainAppender for tests is bounded with drop-oldest; NoOpActionChainAppender is the bootstrap default.

Deck queries the snapshot via MeshDB's MeshQuery::Latest against the snapshot chain — the federated executor routes to a node holding the fold; the result row carries the postcard-encoded snapshot. No new wire protocol, no Deck-specific RPC. The v0.16 federated query plane becomes the v0.17 observability surface.

---

Continuous-rebalance scheduler

The leader-driven scoring loop. For each chain where this node is the elected leader, score every holder via a pluggable PlacementScorer, pick the lowest, and emit RequestEviction when (worst score < score_floor) AND (best alternative > worst + hysteresis_gap) AND (cooldown elapsed):

pub trait PlacementScorer: Send + Sync + 'static {
    fn score(&self, chain: ChainId, node: NodeId) -> Option<f32>;
    fn best_alternative(&self, chain: ChainId, exclude: &[NodeId]) -> Option<(NodeId, f32)>;
}

pub struct SchedulerConfig {
    pub score_floor: f32,            // default 0.5
    pub hysteresis_gap: f32,         // default 0.2
    pub cooldown: Duration,          // default 5 min
}

The trait abstracts the substrate's PlacementFilter so production wires a PlacementFilter-backed impl and tests mock the score table. The eviction emission is idempotent across reconcile passes — a pending_evictions: HashSet<ChainId> written by the loop on each emission and cleared when the fold observes the holder count drop. Phase-C's existing diff observes the holder-count drop and refills via RequestPlacement on the next tick — two-stage rebalance with no new action variant. Per-chain MeshOsState::last_rebalance records the most recent eviction's Instant so the cooldown survives transient state and the same chain doesn't flap A→B→A within the window.

Scheduler emission sorts by chain id for byte-stable output across reconcile calls regardless of HashMap iteration. The scheduler arm short-circuits when Phase C's overcount diff already emitted an eviction for the same chain on the same tick — the two arms can no longer fragment the leader's view of the chain.

---

Single admit() backpressure layer

One function gates every outbound action:

pub enum AdmissionResult {
    Admit,
    Defer { retry_after: Duration },
    Gate { cooldown_until: Instant, reason: &'static str },
}

impl BackpressureState {
    pub fn admit(
        &mut self,
        action: &MeshOsAction,
        now: Instant,
        config: &BackpressureConfig,
    ) -> AdmissionResult { ... }
}

Throttles applied: global pull cooldown (default 250 ms), per-chain replica stabilization (default 60 s), per-daemon gate driven by BackoffTracker::release_at, drain rate-limit (default 10/sec/zone), cluster-wide hysteresis flag (default 1000 high / 200 low). Same admit() for every action variant — a drain-triggered migration cannot dodge the pull cooldown; a crash-looping daemon cannot dodge the gate just because its restart was admin-driven.

The dispatch retry path now routes through admit() rather than directly re-pushing onto the defer heap. BackpressureState::release_failed_admit(action, now) rolls back the per-action reservations (drain_window push, last_pull_admitted stamp, chain_stabilization window) when a dispatch error fires after admit returned Admit — counters no longer drift permanently after transient errors. The defer heap enforces max_defer_count (default 16) before dropping a poison-pill action with a FailureRecord.

ActionExecutor runs update_cluster_backpressure once per handle_one with the current queue depth and surfaces the returned ClusterBackpressureChange through the dispatcher's MeshOsControl::BackpressureOn { level } / BackpressureOff broadcast — the plan's promise is no longer dead code. Per-tick tick() GCs elapsed daemon gates + chain stabilization windows so the state stays bounded under churn.

---

Action executor

Drains the loop's Receiver<PendingAction>, runs each through admit(), dispatches via a pluggable ActionDispatcher, and records the outcome to the action chain:

pub trait ActionDispatcher: Send + Sync + 'static {
    fn dispatch<'a>(
        &'a self,
        action: MeshOsAction,
    ) -> BoxFuture<'a, Result<(), DispatchError>>;
}

pub struct DispatchError {
    pub reason: String,
    pub retry_after: Option<Duration>,
}

LoggingDispatcher ships for bootstrap and tests — records every dispatch in an internal Mutex<Vec<MeshOsAction>> and supports fail_next(err) for exercising the failure / retry paths. Production dispatchers wrap the existing subsystems (DaemonRegistry for start/stop, the migration orchestrator for pull/drop/migrate, the admin chain commit path for CommitMaintenanceTransition).

The executor's with_chain_appender(...) builder installs an ActionChainAppender; the dispatcher, gate, and retry paths all append records via append_dispatched / append_failed / append_gated. The chain replay drives the snapshot's recent_failures ring buffer.

Probe + dispatcher panics are caught via std::panic::catch_unwind; the panic message rides into a FailureRecord and the executor / loop continues. Stats are exposed live via ExecutorHandle::stats() and on shutdown via RuntimeStats.executor.

---

MeshOsRuntime — one-call entry point

impl MeshOsRuntime {
    pub fn start<D: ActionDispatcher>(config: MeshOsConfig, dispatcher: Arc<D>) -> Self;
    pub fn start_with_probes<D: ActionDispatcher>(/* ... */) -> Self;
    pub fn start_full<D: ActionDispatcher>(/* ... */) -> Self;

    pub fn handle(&self) -> &MeshOsHandle;
    pub fn handle_clone(&self) -> MeshOsHandle;
    pub fn snapshot(&self) -> MeshOsSnapshot;
    pub fn snapshot_reader(&self) -> &MeshOsSnapshotReader;
    pub fn executor_stats(&self) -> ExecutorStatsSnapshot;
    pub fn add_locality_probe(&self, probe: Arc<dyn LocalityProbe>);
    pub fn add_health_probe(&self, probe: Arc<dyn HealthProbe>);
    pub fn install_placement_scorer(&self, scorer: Arc<dyn PlacementScorer>);
    pub fn register_daemon(&self, daemon: Box<dyn MeshDaemon>, keypair: EntityKeypair)
        -> Result<DaemonHandle, RuntimeError>;
    pub async fn shutdown(self) -> Result<RuntimeStats, RuntimeShutdownError>;
}

impl Drop for MeshOsRuntime {
    fn drop(&mut self) { /* aborts loop + executor tasks, warns if shutdown wasn't called */ }
}

start(config, dispatcher) spawns the loop + executor as tokio tasks; the returned struct exposes the publish handle, snapshot reader, probe / scheduler registries, executor stats, and a graceful shutdown path. Source-converter helpers (attach_to_daemon_registry, attach_to_replication_coordinator) plug into the runtime's handle.

register_daemon(...) is the daemon-side path — implementors of the extended MeshDaemon trait register through the runtime rather than reaching into the underlying DaemonRegistry. The runtime's Drop impl aborts both tasks (loop + executor) and emits a tracing::warn when shutdown wasn't called explicitly — no more leaked tasks on accidental drop.

MeshOsHandle::publish_timeout(event, Duration) complements publish and try_publish for source converters that need timeout semantics without blocking. The module-level example uses try_publish per the new doc-comment guidance.

---

SDK plan

The MeshOS SDK plan covering Rust / Python / Node / Go / C ships as a design document at docs/plans/MESHOS_SDK_PLAN.md. The Rust SDK is the canonical surface — MeshOsDaemonHandle + daemon_main! macro + integration tests against MeshOsRuntime with LoggingDispatcher. Python (pyo3, sync-first), Node (napi-rs, AsyncIterable control events), Go (cgo + context.Context-aware control channels), and C (vtable + last-error surface mirroring MeshDB's FFI pattern) land in dependency order per consumer demand. A new sdk workspace member at crates/net/sdk/ opens the slot.

The plan locks in ten decisions, most importantly the non-goals: no placement APIs in any binding, no admin-event issuance, no MeshOS-control surfaces. The SDK is the daemon contract, exposed in five languages. Operator tooling, federated interactions, and MeshDB queries belong to separate SDKs.

---

Toolchain + dependency upgrades

No new dependencies. The arc-swap = "1.7.1" already in the workspace gets a new consumer (MeshOsSnapshot publish path). The tracing = "0.1" workspace dep gets a new consumer (every meshos::* module emits debug! / warn! / error! events at lifecycle and failure boundaries). The crate version moves from 0.16.x to 0.17.0; the workspace gains the sdk member at crates/net/sdk/.

The meshos Cargo feature gates the entire surface. It pulls in cortex (which pulls in redex); the substrate builds clean without --features meshos and the meshos cdylib path is purely additive.

---

Test hygiene

• Lib suite at 2715+ tests (was 2645+ at v0.16 release). 200+ net new tests across the MeshOS surface + cross-cutting fixes; every numbered review item from both hardening passes ships with at least one regression where the shape made one possible. Notable additions:
  • Reconcile + scheduler: reconcile::scheduler_eviction_is_idempotent_when_loop_writes_back_last_rebalance, reconcile::phase_c_overcount_eviction_suppresses_phase_d1_eviction_for_same_chain, reconcile::apply_backoff_is_not_re_emitted_after_the_loop_records_it, the 13-test scheduler reconcile arm covering leader-only gating + hysteresis + cooldown + worst-victim selection + chain-id-sorted emission.
  • Backpressure + executor: BackpressureState::release_failed_admit_* (3 cases — pull cooldown, drain window, chain stabilization), executor::cluster_backpressure_edges_surface_through_dispatcher_hook, executor::dispatch_failure_with_retry_releases_pull_cooldown, executor::dispatcher_panic_does_not_kill_executor, executor::dispatch_retry_drops_after_exceeding_max_defer_count.
  • Event loop: event_loop::snapshot_reader_does_not_stall_under_concurrent_reads, event_loop::dropped_actions_counter_increments_when_action_queue_is_full, event_loop::panicking_probe_does_not_kill_the_loop, event_loop::publish_timeout_returns_queue_full_when_loop_is_wedged, event_loop::shutdown_event_short_circuits_pending_events_after_it (re-pinned with actual assertions).
  • State + maintenance: state::enter_maintenance_since_is_anchored_on_last_tick_for_replay_determinism, the MaintenanceState round-trip tests including DrainFailed { reason }, the MaintenanceTransitionObserved gated-state-advance tests.
  • Runtime + chain: runtime::dropping_runtime_without_shutdown_aborts_tasks, runtime::register_daemon_round_trip_through_executor, chain::buffering_appender_drops_oldest_when_at_capacity, chain::decode_rejects_payload_with_unknown_wire_version, chain::decode_rejects_empty_payload, chain::encode_decode_round_trip_preserves_record, the end-to-end executor → buffering appender → fold → snapshot test.
  • Snapshot + sources: snapshot::failure_record_age_ms_derives_from_recorded_at_ms, sources::leader_lost_event_clears_replica_leader_via_none_update.
• cargo clippy --features meshos --all-targets -D warnings clean across substrate + every binding crate.
• cargo doc --features meshos --no-deps clean under RUSTDOCFLAGS="-D warnings" — every public item in the meshos surface carries a doc comment; intra-doc links resolve through the public re-exports.
• 172 meshos unit tests + 11 pipeline integration tests + 13 daemon-registry + 9 daemon-trait + 15 replication-coordinator tests all pass.

---

Breaking changes

API — MeshOS surface is new

MeshOsLoop + MeshOsRuntime + MeshOsHandle + MeshOsSnapshot + MeshOsSnapshotReader + MeshOsState + DesiredState + MeshOsConfig + MeshOsEvent + MeshOsAction + MeshOsControl + ProbeRegistry + SchedulerRegistry + ActionDispatcher + ActionExecutor + ActionChainAppender + every operator family are all new in v0.17. Behind the meshos Cargo feature; non-meshos builds see the substrate path unchanged.

MeshDaemon trait gains three optional methods

health() / saturation() / on_control(DaemonControl) land on the trait itself (not feature-gated) with default impls. Every existing daemon compiles unchanged. DaemonHealth and DaemonControl are new public types in compute::daemon; the latter is the WASM-friendly relative-ms form daemons receive.

DaemonRegistry gains a lifecycle observer

DaemonRegistry::set_lifecycle_observer(Option<Arc<dyn DaemonLifecycleObserver>>) is new. The hot path is unaffected when no observer is installed (one RwLock<Option<Arc>> read + is_none check). The unregister path uses try_lock against the inner Mutex to avoid a deadlock when called from inside a with_host closure on the same id; observers see an empty name on that path and correlate by id with the prior Registered event.

ReplicationCoordinator gains a transition observer

ReplicationCoordinator::set_transition_observer(Option<Arc<dyn ReplicaTransitionObserver>>) is new. BecameHolder / Idled / LeaderChanged / LeaderLost events fire from the successful path of transition_to after the chain-tag side effect lands.

Workspace — new sdk member

crates/net/sdk/ is a new workspace member. The slot opens for the Rust MeshOS SDK; the directory is empty in this release and populates once the SDK plan's Phase 1 lands.

Behavioral fixes that may surface as test breakage

• MissedTickBehavior::Delay replaces Skip on the loop's heartbeat timer. Tests that asserted skipped ticks under load will see delayed ticks instead.
• MeshOsRuntime::drop aborts both tasks. Tests that relied on the loop / executor running past a dropped runtime will see the tasks aborted.
• MeshOsHandle::publish is still async-blocking on a full queue; tests that hung previously now have publish_timeout(event, Duration) available as a non-blocking-on-deadline alternative.
• Probe panics no longer kill the loop. Tests that asserted JoinError::Panic propagation through the loop task will see the probe's panic surface in recent_failures instead.

---

How to upgrade

1. Bump your Cargo.toml / package.json / requirements.txt / go.mod to the v0.17 line. Recompile / rebuild the binding cdylib with the meshos Cargo feature on when you want the MeshOS surface; without it, the substrate is unchanged from v0.16.
2. MeshOS opt-in. Channels that want the cluster-behavior engine: build the substrate with --features meshos and call MeshOsRuntime::start(MeshOsConfig::default(), dispatcher) where dispatcher wires MeshOsAction variants to the existing subsystems (DaemonRegistry for StartDaemon / StopDaemon, the migration orchestrator for PullReplica / DropReplica, the admin-chain commit path for CommitMaintenanceTransition).
3. Source converters. Attach the daemon-registry sink via attach_to_daemon_registry(&registry, runtime.handle_clone()). Attach a per-coordinator replica sink via attach_to_replication_coordinator(&coord, runtime.handle_clone(), this_node). Install proximity probes via runtime.add_locality_probe(...) and runtime.add_health_probe(...) against a shared Arc<ProximityGraph>.
4. Placement scorer. Install a PlacementScorer impl via runtime.install_placement_scorer(scorer). The substrate ships the trait + scheduler arm; the impl wires to PlacementFilter per consumer.
5. Action chain. Install an ActionChainAppender on the executor (production: writes to a RedEX chain that the MeshOsSnapshotFold consumes on every node). The default NoOpActionChainAppender makes the chain optional; Deck integration drives the wiring.
6. Daemon trait additions. If you implement MeshDaemon and want supervision participation: override health() / saturation() / on_control(DaemonControl). Defaults preserve compatibility; overrides opt into graceful shutdown, drain coordination, and cluster-wide backpressure.
7. Shutdown. Always call runtime.shutdown().await rather than dropping the runtime. The new Drop impl aborts the tasks and warns, but an explicit shutdown is the contract for clean lifecycle.
8. Snapshot consumers. Read the snapshot via runtime.snapshot() (cheap — one ArcSwap::load_full) or sample executor stats via runtime.executor_stats(). Deck queries arrive through MeshDB once the snapshot chain is wired.

Dataforts

Dataforts in Net is the data layer that grows on top of the event bus, and v0.15 is where it lands. Every prior approach to "where does the data live" presupposes an answer — S3 holds it in a region, Ceph holds it across racks, IPFS holds it wherever a pin exists. Storage is a place. You go to the place to read. You ship to the place to write. Dataforts inverts that: blobs are content-addressed BLAKE3 chunks, the address of the data is the data, and the chunks live on whichever nodes have capacity and capability to hold them. There is no canonical home.

Data in Dataforts is a fluid. Hot chunks — bytes that some node keeps fetching — get pulled toward the nodes that read them, because re-fetching the same hash leaves a copy behind. Cold chunks stay where they are or drain into nodes with spare disk. The same pressure that fills a near-empty node also empties a near-full one. Nothing tells the cluster to rebalance. The blobs move because the reads moved.

Heat is per-chunk and decays. A chunk read a hundred times in the last minute has gravity; a chunk read once a year ago has none. The capability index advertises heat the same way it advertises disk-free, scope, and class. A peer with gravity for a given hash is the natural target when the chunk's current holder needs to shed, and the natural source when a new reader asks. Migration is the heat reading itself — no scheduler, no shuffle plan, no coordinator deciding where bytes should be. The reads decide.

When a node crosses its high-water disk threshold, it picks the coldest chunks it holds and pushes them to peers with capacity. The receive side is opt-in via a capability tag — operators decide which nodes accept overflow and which stay pull-only. Pushes ride the existing per-chunk replication runtime; the only new wire shape is a one-shot nudge telling the receiver to open the chunk channel. Storage saturation no longer fails closed against new writes — the cluster bleeds pressure into peers that can absorb it, until either the workload subsides or those peers fill up too.

A producer that publishes a chunk and immediately reads it back never sees a gap. The publish path returns a write token; the read path waits on that token's durability watermark before returning the bytes. Read-your-own-writes is the producer's contract with itself — independent of replication factor, independent of cluster topology, independent of which peer ends up holding the chunk. The mesh doesn't promise global linearizability. It promises that you see what you just wrote, however many hops the bytes had to take to settle.

These properties compose with the rest of the stack. RedEX writes a BlobRef into the event chain like any other event — the substrate verifies the BLAKE3 hash, the chain stays causal, the blob payload pulls separately when somebody needs it. CortEX folds events that reference blobs into views; the views pin the chunks they care about so gravity doesn't sweep them away. A drone, a workstation, and a datacenter can hold the same dataforts — different slices of the same content-addressed space, replicating according to who reads what, all encrypted in flight and on disk.

There is no object store to provision. There is no cluster to operate. The data is on the mesh because the mesh is the data.

---

Named after Billy Idol's 1983 album / title track — a release that asks "more, more, more" of the substrate The Warriors laid down. v0.14 made replication the load-bearing layer underneath the channel surface. v0.15 stacks the four-phase Dataforts compositional layer on top: greedy-LRU caching pulls in-scope chains, data gravity drifts hot ones toward their readers, BlobRef carries content-addressed pointers without owning the bytes, and read-your-writes gives producers a session-bounded "did my write land yet?" handle. No new wire protocol — every phase composes against the existing capability index, proximity graph, and causal: tag layer that landed in The Warriors.

v0.15 lands the full Rebel Yell roadmap from DATAFORTS_PLAN.md — Phases 1, 3, 4, and 5 of the seven-phase plan ship in this release, completing Dataforts as a compositional data plane on top of the v0.14 substrate. The full surface ships across Rust core, Python, Node, Go, and C FFI, with end-to-end mesh integration; greedy and gravity are runtime-toggleable policies (operators flip them on / off live against a running mesh, no rebuild required); the single dataforts Cargo feature gates whether the surface compiles at all. A mesh-native blob storage extension (Phase 3.5) lands in the same release — MeshBlobAdapter implements the v0.15 BlobAdapter trait against the local mesh's RedEX replication layer, so a Dataforts-enabled cluster has a working content-addressed blob store the moment Redex::enable_replication(mesh) is called. See DATAFORTS_BLOB_STORAGE_PLAN.md for the design. The v0.3 active-overflow extension ships alongside — disabled by default, one boolean to turn on; when active, a node pushes its coldest blobs to overflow-enabled peers with free disk via a new nRPC. Design + per-PR shipping status in DATAFORTS_BLOB_OVERFLOW_PLAN.md.

The hardening posture from the Black Diamond line continues. Two coordinated code-review passes landed before the v0.15 branch cut: the primary dataforts-feature review (docs/misc/CODE_REVIEW_2026_05_11_DATAFORTS.md) closed 54 numbered items D-1..D-54, an independent second pass surfaced 11 N-series items, all but three (deferred with rationale) closed. Five post-merge follow-up commits on the channel-hash-32 branch hardened the RPC-inbound dispatcher hot path and tightened collision-lookup contracts.

Alongside Dataforts, v0.15 carries one cross-cutting breaking change: the canonical channel hash widens from u16 to u32 substrate-wide. The wire NetHeader::channel_hash stays u16 (the 64-byte cache-line-aligned header is full), mirroring the origin_hash u64-canonical / u32-wire precedent. ACL, storage, config, and RYW decisions key on the canonical 32-bit hash; the wire u16 is a fast-path filter hint only. The PermissionToken wire form grows from 159 → 161 bytes.

---

Greedy-LRU dataforts (Phase 1)

Per-node speculative caching of in-scope chains observed via the tail-subscription path. The mesh fans every event through a GreedyObserver hook; the runtime decides whether to admit each event into a per-channel cache file. Cold channels evict under cluster-cap pressure and withdraw their causal:<hex> advertisement so peers re-route to a healthy holder. Wires via Redex::enable_greedy_dataforts(mesh, config, local_caps, intent_registry).

GreedyConfig

pub struct GreedyConfig {
    pub scopes: Vec<ScopeLabel>,           // scope-axis admission
    pub proximity_max_rtt: Option<Duration>, // proximity-axis admission
    pub per_channel_cap_bytes: u64,        // storage-axis admission, per chain
    pub total_cap_bytes: u64,              // cluster-cap eviction trigger
    pub bandwidth_budget_fraction: f32,    // share of measured NIC peak
    pub nic_peak_bytes_per_s: Option<u64>, // operator override of probe
    pub intent_match: IntentMatchPolicy,   // capability-preference axis
    pub colocation_policy: ColocationPolicy, // colocation axis
    pub observer_inflight_cap: usize,      // tokio spawn fan-out bound
}

The five admission axes (scope + proximity + capability-preference + colocation + storage-cap) gate every inbound event before the bandwidth-budget gate; rejected events bump the per-reason counter rather than entering the cache file. A bandwidth-budget rejection now increments a distinct dataforts_greedy_admit_throttled_bandwidth_total counter (was conflated with capacity-rejects pre-fix) so operators can disambiguate "NIC saturated" from "cache full." nic_peak_bytes_per_s overrides the hardcoded 1 Gbps default for fleets with faster NICs.

Admission + eviction

Inbound events flow through GreedyRuntime::dispatch_event(channel_name, channel_hash, origin_hash, chain_caps, payload). Admission is a pure function — should_admit(inputs) -> AdmissionVerdict — that returns one of Admit / RejectedByAdmission(AdmitRejectReason). The bandwidth-budget gate runs only after admission passes; admitted events that fail the budget gate are throttled, not silently dropped (D-2). Eviction under the cluster cap returns an EvictionSweep { evicted: Vec<EvictedEntry> } value; the runtime calls sink.withdraw_chain(origin_hash) for each evicted entry inline so peers see the capability tag drop in the same tick (D-1).

The cache-side RedexFile keys on a synthesized ChannelName (dataforts/greedy/<hex16>) derived from the wire u16 channel hash; the canonical 32-bit hash decision happens at the ACL / config / RYW layer, not at the data-plane cache (the wire hash is what inbound packets carry). Two channels colliding on the wire u16 share a cache file — a small mix-up at the data-plane layer; ACL and storage decisions stay collision-safe via the canonical hash.

TOCTOU + lock-coalescing fixes

is_new_channel = !cache.contains(channel) followed by cache.upsert(...) previously took two independent lock acquisitions; concurrent dispatch_event calls on the same channel both observed is_new_channel = true, both ran sink.announce_chain, and the second upsert orphaned the first RedexFile. v0.15 folds the lazy-open into a single cache.get_or_insert_with scope holding the lock for contains / open / upsert; announce fires after lock release. The steady-state path takes one lock; the new-channel path takes two with TOCTOU re-check (D-6, D-28).

upsert on an already-registered channel previously refreshed the file pointer without subtracting the prior entry's bytes from total_bytes. Reopens via dispatch_event's is_new_channel path accumulated total_bytes that no eviction could ever drain, eventually starving the cluster-cap budget. The update branch now subtracts the prior bytes before replacing the entry's file (D-3).

entry.bytes saturates on overflow but didn't reflect retention trim from RedexFile. v0.15 ships RedexFile::retained_bytes + GreedyRuntime::resync_cache_bytes for periodic operator-driven re-anchoring; wiring is opt-in via the operator's tick loop (D-26).

colocation_target_held resolved from cache

ColocationPolicy::SoftPreference / StrictRequired evaluates whether the local cache already holds chains colocated with the inbound event. The pre-fix colocation_target_held = None hardcode caused StrictRequired to reject events whose colocation target was actually present locally. The runtime now resolves the colocation target by name against the cache map (D-8).

Spawn fan-out bound

observe_event is the mesh hot-path entry; without a bound, a flooding peer could create one outstanding tokio task per event before the per-event admission lock serialized them, piling up per-task Bytes + Arc<CapabilitySet> clones. v0.15 ships observer_inflight: Arc<tokio::sync::Semaphore> sized via GreedyConfig::observer_inflight_cap (default 4096); on saturation, events drop and bump dataforts_greedy_observer_dropped_overloaded rather than blocking the mesh dispatch task (D-7).

Cross-binding API surface

Every binding exposes the same enable_greedy_dataforts / disable_greedy_dataforts pair plus greedy_cached_channel_count() and greedy_prometheus_text() for operator scrape. The Go binding carries the runtime-stub fallback (NET_ERR_FEATURE_NOT_BUILT) so a cdylib built without the dataforts feature still links cleanly into cgo programs (D-20).

---

Data gravity (Phase 4)

Per-chain read-rate counters with exponential decay. Threshold-crossing emissions stamp heat:<hex>=<rate> onto the chain's existing capability announcement; greedy admission weights cache pulls by heat × scope-match × proximity-rank. Cold chains evict first under cluster-cap pressure; hot chains migrate toward the readers that drive the heat. No separate migration engine — gravity emerges from greedy + heat counters + capability-preference automatically.

Wires via Redex::enable_gravity_for_greedy(mesh, DataGravityPolicy) against an already-running greedy runtime.

DataGravityPolicy

pub struct DataGravityPolicy {
    pub enabled: bool,
    pub emit_threshold_ratio: f64,         // 1.5 = re-emit when rate is 1.5× last-announced
    pub decay_half_life_secs: u64,         // 300 = 5-minute half-life
    pub tick_interval_ms: u64,             // 5000 = 5-second tick cadence
    pub normalization_reference_rate: f64, // 1000 events/s → 1.0 on the wire
}

Heat counter + emission decision

HeatCounter::observe(now, weight) bumps the counter; HeatCounter::current_rate(now) returns the decayed rate. should_emit_heat(prev, current, ratio) is the pure-logic emission decision: emit when no prior emission, or when the current rate exceeds prev × ratio or falls below prev / ratio. Edge cases:

• Near-zero prev no longer trips inf. Pre-fix, a prev of 1e-300 with finite current made current / prev evaluate to +inf, which trivially satisfied any ratio check. v0.15 treats prev below f64::EPSILON (and subnormals via is_normal()) as "no prior emission" — the bootstrap arm runs cleanly (D-29, N-9).
• NaN rates short-circuit to no-emit. A NaN slipping into the counter (e.g. via a corrupted to_le_bytes round-trip on the wire) used to propagate through the ratio arithmetic. The pure function now returns EmissionDecision::Skip on any non-finite input.

Wire normalization — log-scale

Pre-fix, the wire heat:<hex>=<rate> tag normalized (rate / (rate + 1)).min(1.0), which compressed asymptotically — rate=10 → 0.91, rate=100 → 0.99. With {:.2} wire encoding, every "warm" chain looked like "blazing." v0.15 uses ln_1p(rate) / ln_1p(reference) with a configurable normalization_reference_rate; the reference defaults to 1000 events/s mapping to 1.0 on the wire. Wire format is unchanged — just the value placed on it (D-30, D-46).

HeatRegistry cap + LRU

HeatRegistry previously grew unbounded — one entry per (channel, origin) pair the local node ever observed. A misbehaving peer flooding diverse origin hashes could exhaust memory before any greedy-eviction signal fired. v0.15 caps the registry at DEFAULT_HEAT_REGISTRY_CAP = 8 * 1024 entries with LRU eviction by last_update; the tick loop also prunes entries with rate == 0.0 && last_emitted == Some(0.0) so cold chains drain on their own (D-10, N-2).

Inbound heat: tag auth

Capability announcements carrying heat:<hex> tags previously had no provenance check at the receive side — any peer could emit a heat tag claiming any chain. v0.15 gates inbound heat tags on the publisher's existing causal:<hex> claim: a node advertising heat:X without simultaneously advertising causal:X has its heat tag dropped at the receive boundary (D-11). Per-peer rate-limiting of heat: emissions is acknowledged in D-11 + N-8 as deferred — operators see today's posture in CODE_REVIEW_2026_05_11_DATAFORTS.md.

origin_hash == 0 no longer collapses heat

Default-constructed publishers carried origin_hash = 0, which collapsed all unattributed chains into a single registry bucket and stamped a meaningless heat:0000…0000 tag onto the wire. v0.15 stamps origin_hash from identity in publish_to_peer (the natural fix) and skips heat bumps when origin_hash == 0 is observed at the gravity-runtime entry as defense-in-depth (D-9).

announce_heat_batch — coalesced rebroadcast

gravity_tick previously walked all heat emissions and called announce_heat per chain. Each announce_heat rewrote the full CapabilitySet::tags vector and called announce_capabilities — at 100 K chains, O(n² × n_tags) per tick with each emit duplicating all chains' tags on the wire. v0.15 ships HeatSink::announce_heat_batch; the tick gathers all emissions, retains all stale heat tags + pushes all new heat tags in one pass, and emits a single announce_capabilities (D-25).

---

BlobRef + BlobAdapter (Phase 3)

Content-addressed reference whose bytes live in the caller's existing storage (S3, Ceph, IPFS, local FS, …). The substrate carries the reference, never owns the bytes. Adapters implement fetch / store (or the streaming variants for multi-GB payloads); the FileSystemAdapter ships in-tree as the reference adapter.

Wire format

[0xB0, 0xB1, 0xB2, 0xB3]  // 4-byte magic (was single-byte 0xB0 pre-fix)
version: u8               // currently 1
hash:    [u8; 32]         // BLAKE3
size:    u64              // bytes; bounded by BlobRef::MAX_SIZE = 16 GiB
uri:     [u8]             // length-prefixed; the adapter URI scheme prefix

Pre-fix the discriminator was a single byte 0xB0 (D-14). A plain binary payload starting with 0xB0 would misclassify as a blob ref and route through BlobAdapter::fetch instead of being delivered directly. The 4-byte magic gives a collision probability of ~1 in 4 billion against arbitrary binary payloads. Old (pre-v0.15) blob refs are rejected on decode; v0.15 nodes can't exchange blob refs with pre-v0.15 nodes (Dataforts is new in v0.15, so this only matters for pre-release pilots).

BlobRef::MAX_SIZE = 16 GiB defaults bound the size field; BlobRef::decode and publish_blob reject anything larger. The previous u64::MAX accept-anything path could OOM on vec![0u8; len as usize] on 64-bit and silently truncate on 32-bit (D-15). RedexFileConfig::blob_max_size lifts the cap when an operator needs it.

Adapter dispatch — URI-scheme keyed

BlobAdapter::accepted_schemes() -> &[&str] declares the URI schemes the adapter handles (["s3", "s3+https"], ["file"], etc.); the registry dispatches by URI scheme, not by the channel config's blob_adapter_id. Pre-fix, an attacker who could write to a channel could choose its blob_adapter_id and route a BlobRef URI through any registered adapter — authority confusion (D-13). The scheme-keyed dispatch closes the gap; the channel-config-selected path is gone.

Hash verification on store

FileSystemAdapter::store(blob_ref, &bytes) now BLAKE3-hashes the supplied bytes and rejects on mismatch with blob_ref.hash. Pre-fix the adapter wrote whatever bytes the caller passed; a content-address-violating store would silently corrupt the addressable layer (D-12). The rename-fallback path (idempotent re-store on existing content) also hash-verifies the on-disk bytes — the v0.13/v0.14-era TOCTOU on idempotent re-store via the windowed rename is closed (D-32, N-6).

fsync of the temp file before rename + fsync of the parent dir after rename land in the FileSystemAdapter store path; power loss between rename and OS flush previously left zero-length files in the addressable space (D-33).

Streaming hooks

fetch_stream(&self, blob: &BlobRef) -> Pin<Box<dyn Stream<Item = Result<Bytes>> + Send>> and store_stream(&self, blob: &BlobRef, src: Pin<Box<dyn Stream<...>>>) ship as required methods on BlobAdapter with default implementations that route through the existing fetch / store (so existing impls keep working); adapters wanting real streaming override the defaults. The FileSystemAdapter chunks at 256 KiB (D-16).

Per-channel adapter override (multi-tenant)

BlobAdapterRegistry previously lived as a single process-wide singleton. v0.15 adds RedexFileConfig::blob_adapter_registry: Option<Arc<BlobAdapterRegistry>> for per-channel override; the default-tenant path uses the global singleton unchanged (D-34).

Bounded concurrency on the FS adapter

spawn_blocking calls on the FileSystemAdapter are bounded via tokio::sync::Semaphore. Pre-fix, a fanout of concurrent stores could exhaust the tokio blocking pool and deadlock unrelated tasks (D-35).

Conformance suite

The blob adapter conformance suite extends to cover idempotency (re-store same hash), hash-mismatch rejection, range-past-end behavior, cross-blob isolation (writes to blob A can't leak into blob B's namespace), and random-ghost reads (resolve a never-published BlobRef). Adapter authors pin against the same suite the in-tree FileSystemAdapter does (D-36).

Cross-binding adapter authoring

Adapters can be written in the host language across every binding:

• Python — PyBlobAdapter with sync + async def method support. Async adapters run on a binding-owned event loop on a dedicated thread (one loop per process); calling thread sharing is via asyncio.run_coroutine_threadsafe. An aiobotocore / httpx.AsyncClient / SQLAlchemy async engine inside the adapter is safe — the binding never spins up a fresh asyncio.run per call (D-4).
• Node — NodeBlobAdapter (sync TSFN bridge) + NodeAsyncBlobAdapter (Promise-returning TSFN bridge).
• C / cgo — NetBlobAdapterVtable with per-field null-check at registration; partial vtables return NET_ERR_BLOB_VTABLE_INVALID rather than crashing on first dispatch (D-22).

BlobError::NotFound(uri) sanitizes the URI before including it in the error string — control chars escape as \xNN, length caps at 256 bytes — so a binding logging the error can't be log-injected by an attacker who controls the URI (D-31).

---

Mesh-native blob storage (Phase 3.5)

Phase 3's BlobRef + BlobAdapter hook treats the substrate as a carrier for content-addressed pointers — the bytes live in S3 / Ceph / IPFS / the local FS. Phase 3.5 extends that hook with a substrate-owned content-addressed store: MeshBlobAdapter implements BlobAdapter against the local mesh's RedEX replication layer, registered under the mesh:// URI scheme. A Dataforts-enabled cluster has a working blob store the moment Redex::enable_replication(mesh) is called; operators pick a replication_factor instead of standing up a separate storage system.

The full plan + design rationale lives in DATAFORTS_BLOB_STORAGE_PLAN.md. Shipped as PR-5a through PR-5r + a post-feature hardening bundle.

MeshBlobAdapter

let adapter = MeshBlobAdapter::new("mesh-prod", redex.clone())
    .with_persistent(true)
    .with_replication(ReplicationConfig::factor(3))
    .with_retention_floor(Duration::from_secs(24 * 3600))
    .with_disk_capacity(1 << 40)
    .with_auth_guard(auth_guard.clone())
    .with_blob_heat(blob_heat_registry, Duration::from_secs(60));

Implements BlobAdapter::{store, fetch, fetch_range, exists, delete, stat, prefetch} plus store_stream / fetch_stream for multi-GB payloads. store BLAKE3-verifies the supplied bytes against blob_ref.hash before persisting; idempotent — repeated stores of identical bytes against the same hash are a no-op. Chunks above the 4 MiB threshold split into independently-content-addressed RedexFiles, with a small manifest blob (one BlobRef::Manifest) carrying the chunk list.

BlobRef::Manifest + chunking

BlobRef gains a Manifest { encoding, chunks: Vec<ChunkRef>, size } variant alongside the v0.15 Small. Wire form is forward-compatible — the 4-byte magic + version byte gate variants. Encoding::Replicated ships in v0.2; Encoding::ReedSolomon { k, m } is reserved on the wire for v0.3. Chunking is fixed-size 4 MiB; a 16 GiB blob holds 4096 chunk references (≈144 KiB manifest, within the inline path itself).

publish_with_blob — store-then-publish

let receipt = mesh.publish_with_blob(
    channel,
    payload_bytes,
    BlobDurability::ReplicatedTo(3),
).await?;

Stores the bytes to the configured durability, then publishes an event referencing the resulting BlobRef. The receipt carries a WriteToken whose applied_through_seq watermark composes with Phase 5's read-your-writes — a consumer calling tasks.wait_for_token(token, deadline) blocks until both the publish event has folded and the chunks have replicated to the requested durability. BlobDurability::{BestEffort, DurableOnLocal, ReplicatedTo(n)} chooses the trade-off between latency and the durability guarantee the receipt asserts.

Refcount + GC + pinning

BlobRefcountTable tracks per-hash references from three sources: RedEX chain folds (PR-5h wires greedy into the increment / decrement path on cache admit / eviction), CortEX adapters indexing events, and direct pin(blob_ref) / unpin(blob_ref) operator calls. sweep_gc(now, disk_pressure) collects refcount = 0 + unpinned hashes whose first_seen is older than the retention floor (default 24 h); disk_pressure = true bypasses the floor for emergency reclaim. delete_chunk drops the refcount entry inline rather than waiting for the sweep.

A health gate advertises dataforts:blob-storage-unhealthy when local disk crosses 95 % and clears at 85 % (hysteresis); other nodes' admission filters reject inbound migrations to an unhealthy node.

Capability extension

Three new capability families compose against the existing 5-axis PlacementFilter:

• BlobCapability — storage, disk_total_gb, disk_free_gb, class.
• GreedyCapability — enabled, scope, proximity. Same shape as the chain-side greedy gate; blobs reuse the chain proximity score.
• GravityCapability — enabled, scope, proximity. Independent of greedy; a node can participate in gravity migration without speculatively greedy-pulling.

PlacementFilter gains an Artifact::Blob { blob_hash, size_bytes, encoding, capabilities } variant; the score function reads blob.disk_free_gb + blob.storage + gravity.scope to gate blob placement.

TopologyScope (Node ⊂ Zone ⊂ Region ⊂ Mesh) is a hard boundary on greedy / gravity decisions — scope == Zone means the local node never pulls or accepts migration of a blob whose publisher is in a different zone.

G-1 / G-2 / G-3 — admission, gravity, migration

Three pure-logic decision primitives plus the runtime that consumes them:

• should_pull_blob(local_caps, publisher_caps) (G-1). Greedy admission verdict: Admit / Reject(reason) where reason ∈ { NoStorageCap, GreedyDisabled, ProximityZero, Unhealthy, ScopeMismatch }. Wired into GreedyRuntime::dispatch_event so admitted chains carrying BlobRefs trigger a BlobAdapter::prefetch on the referenced blob. Counters: dataforts_greedy_blob_pulls_admitted_total / …_rejected_total{reason}.
• should_migrate_blob_to(target_caps, publisher_caps, size_bytes) (G-2 / G-3). Gravity migration verdict for target_caps; extends the should_pull_blob shape with a disk_free_gb headroom check (rounded up — 1.5 GiB blob → ceil(1.5) = 2 GiB required). MigrateBlobReject::InsufficientDisk is the additional variant.
• drive_blob_migration_tick(local_caps, capability_index, adapter, size_resolver) + the _with_manifest_resolver variant. Walks peers in the capability index, parses heat:blob:<hex>=<rate> reserved tags via parse_blob_heat_tag, runs should_migrate_blob_to against each candidate, and on admit calls adapter.prefetch. The manifest-resolver variant recursively prefetches every constituent chunk of a BlobRef::Manifest (PR-5o). Returns a BlobMigrationTickReport with per-reason counters for operator dashboards.

Per-node pull, not centralized push — each node decides what to pull from its local capability view. The plan documents the storage-overflow push-to-peer track as deferred future work.

Blob heat — heat:blob:<hex>=<rate> tags

Mirrors the chain-side gravity layer with a key-shape change: blob heat keys on the 32-byte chunk hash. BlobHeatRegistry (LRU + cap + half-life decay, same discipline as HeatRegistry); MeshBlobAdapter::with_blob_heat(registry, half_life) opts the adapter into bumping heat on every successful fetch / fetch_range. MeshBlobAdapter::tick_blob_heat(policy, sink) walks the registry and routes Emit { rate } / Withdraw decisions through the BlobHeatSink trait; MeshNode implements the sink by adding a heat:blob:<hex64>=<rate> reserved tag to the local capability set and rebroadcasting via announce_capabilities.

The blob: body sub-prefix keeps blob-heat tags disjoint from chain-heat tags on the wire (heat:<origin_hex>=<rate> for chains, heat:blob:<hash_hex>=<rate> for blobs).

G-6 — Auth

pin_authorized / unpin_authorized / delete_chunk_authorized gate on AuthGuard::is_authorized_full(origin, channel) against the chain that originally published the blob. The unauth pin / unpin / delete_chunk variants remain available for system-internal callers (GC sweep, chain-fold refcount increment / decrement). BlobError::Unauthorized is the typed rejection.

net-blob operator CLI

Operator surface shipped behind the new cli Cargo feature (features = ["dataforts", "redex-disk", "cli"]). Subcommands:

• net-blob put <path> — store + return the resulting BlobRef.
• net-blob get <hash> --out <path> — fetch; refuses to clobber existing output files.
• net-blob exists <hash> — exit 0 if present, exit 1 if absent.
• net-blob stat <hash> — refcount + size + last-seen.
• net-blob ls — list known content hashes.
• net-blob pin <hash> / net-blob unpin <hash> — operator pin / unpin.
• net-blob gc [--retention <duration>] [--dry-run] [--disk-pressure] — GC sweep. --dry-run lists candidates; --disk-pressure bypasses the retention floor.
• net-blob metrics — Prometheus text body.

--format json is available across every subcommand for scripting; parse_duration accepts 30s / 5m / 1h / 24h / 7d.

Cross-binding — Python

net.MeshBlobAdapter lands in the Python binding behind --features dataforts. Methods: store(blob_ref, data), fetch(blob_ref) -> bytes, fetch_range(blob_ref, start, end) -> bytes (half-open [start, end)), exists(blob_ref) -> bool, prometheus_text() -> str. Plus a PyBlobRef constructor taking (uri, hash_bytes, size) and round-tripping through encode() / BlobRef.from_encoded(bytes). Persistent mode (MeshBlobAdapter(redex, "id", persistent=True)) writes per-chunk RedexFiles to disk.

Node + Go binding wrappers for the v0.2 MeshBlobAdapter surface are tracked as deferred per-binding follow-ups in the plan doc.

Hardening — post-PR-5j review pass

Eighteen commits between PR-5r and the v0.15 cut closed second-pass review items. Grouped by area:

DoS surfaces

• MeshNode::filter_unauthorized_heat_tags caps incoming heat:blob: tags at 256 per announcement; the cap bounds migration-controller amplification (each surviving heat tag drives a prefetch attempt).
• CapabilityIndex::by_origin_hash is a u32-truncated shortcut; an AtomicU64 collision_count field surfaces last-writer-wins collisions on the admission hot path for operator observability (a wire-format-preserving fix; full collision-safe indexing is out of scope for v0.15).
• BlobMigrationController caps per-peer prefetch admits per tick so a single peer can't dominate the disk-bandwidth budget.
• Per-channel chain_blob_refs shadow set in the greedy runtime is bounded; a misbehaving publisher can't inflate per-channel memory unboundedly.

Soundness

• Python &[u8] adapter parameters (PyMeshBlobAdapter::store, blob_publish, blob_resolve) now copy bytes under the GIL (data.to_vec()) before py.detach(). PyO3 0.28's strict &[u8] type-rejects bytearray at the FFI boundary; the post-fix copy keeps the capture-then-detach pattern safe against a hypothetical future PyO3 relaxation.
• CapabilityIndex fails closed when a wire u32 origin_hash is ambiguous and falls back to the empty-caps default for vacant slots.
• MeshBlobAdapter serializes concurrent stores against the same hash through a per-hash lock and BLAKE3-verifies bytes already on disk match the content address before short-circuiting the idempotent re-store path.

Races

• gravity_tick captures sink + emissions + policy under one read of the gravity RwLock. Pre-fix it took the lock twice; a concurrent set_gravity / clear_gravity between reads could renormalize emissions computed under policy A against policy B.
• drive_blob_migration_tick_with_manifest_resolver only inserts hashes into the dedup set after a successful Admit + Ok prefetch; rejected siblings + prefetch errors stay reconsiderable when the same hash surfaces under a later candidate's manifest expansion.
• BlobMigrationController floors the publisher-scope check at the narrowest claim across all heat advertisers for the same hash so a single broad-scope peer can't bypass a narrower-scope peer's gate.

Label injection

• Operator-supplied adapter_id is escaped per the Prometheus text-exposition spec (\\, \", \n) before being interpolated into label values. A --adapter-id 'evil"\n# bogus_metric{} 1\n#' payload can't inject fake metric lines.

Operator-surface hardening

• net-blob get --out refuses to clobber existing output files (the CLI may run with elevated privileges).
• delete_chunk drops the refcount entry inline rather than waiting for sweep_gc.
• BlobError::Unauthorized typed variant separates auth-rejection from other rejection modes.

Build graph

• dataforts = ["redex", "redex-disk", "dep:blake3"]. --features dataforts alone previously failed to compile because the blob path calls RedexFile::sync() which is gated behind redex-disk. The feature graph now encodes the actual dep.

Doc + test-name polish

• Two pull_rejects_* admission tests asserted Admit (Zone-narrower-than-Mesh + absent-publisher-scope-defaults-to-Mesh) — renamed to pull_admits_*.
• controller_skips_peers_without_blob_heat_tags renamed to controller_ignores_chain_heat_shape_tags.
• BlobRef::encoded_len doc now documents Small as O(1) and Manifest as full-encode-cost (was "cheap for both variants").
• PyMeshBlobAdapter::fetch_range doc spells out half-open [start, end) tied to Python slice semantics.
• publish_with_blob doc drops the overstated atomicity claim and documents chunk-advertise ordering inline.

The full per-commit log lives in the plan doc's Shipping status table under "Hardening — post-PR-5j hardening pass."

---

Active blob overflow (Phase 3.5 / v0.3 blob track)

v0.2 mesh-native blob storage is intentionally pull-only — when a node fills up, it advertises dataforts:blob-storage-unhealthy and other nodes' admission rejects inbound migrations. The local node never pushes its own blobs elsewhere; under sustained saturation a node either reclaims via GC or stops accepting new bytes. The v0.3 active-overflow extension closes the loop: when a node fills up, it picks coldest blobs by inverse blob-heat and pushes them to peers that have free disk and have opted into receiving overflow.

The plan + design rationale lives in DATAFORTS_BLOB_OVERFLOW_PLAN.md. Shipped as P1..P5 across five commits on the dataforts-overflow branch.

Disabled by default, one boolean to turn on

Active overflow is off in v0.2 deployments — every existing call site keeps the v0.2 pull-only posture without code changes. To opt in, operators flip a single boolean on the adapter:

// Construction-time, simple form:
let adapter = MeshBlobAdapter::new("mesh-prod", redex.clone())
    .with_overflow(OverflowConfig { enabled: true, ..Default::default() });

// Or with typed tunables:
let adapter = MeshBlobAdapter::new("mesh-prod", redex.clone())
    .with_overflow(OverflowConfig {
        enabled: true,
        high_water_ratio: 0.80,
        low_water_ratio: 0.65,
        max_pushes_per_tick: 8,
        scope: TopologyScope::Zone,
        tick_interval_ms: 30_000,
    });

// Runtime toggle — no rebuild:
adapter.set_overflow_enabled(true);
adapter.set_overflow_enabled(false);

When enabled, the adapter advertises dataforts.blob.overflow on its capability set; peer-selection on the push side filters by this tag so overflow targets only nodes that have themselves opted in. Symmetric opt-in: the receive-side admission gate rejects pushes from a sender that isn't overflow-enabled.

OverflowConfig thresholds

pub struct OverflowConfig {
    pub enabled: bool,                  // master switch
    pub high_water_ratio: f64,          // 0.85 default — triggers tick
    pub low_water_ratio: f64,           // 0.70 default — clears tick (hysteresis)
    pub max_pushes_per_tick: usize,     // 16 default — bandwidth burst cap
    pub scope: TopologyScope,           // Mesh default — push-target scope bound
    pub tick_interval_ms: u64,          // 30_000 default
}

Hysteresis mirrors the existing dataforts:blob-storage-unhealthy health-gate (95% / 85%) with looser thresholds because overflow fires before the unhealthy advertisement — by the time a node is unhealthy, overflow has already been shedding for a while.

G-7 — Active overflow admission

pub fn should_accept_overflow_from(
    local_caps: &CapabilitySet,
    sender_caps: &CapabilitySet,
    blob_size_bytes: u64,
) -> OverflowVerdict;

Receive-side mirror of should_migrate_blob_to. Six ordered gates: NoStorageCap → NotParticipating → SenderNotOverflowing → Unhealthy → ScopeMismatch → InsufficientDisk. Each OverflowReject variant maps to a distinct Prometheus counter label so operators dashboard both sides.

The ordering matters operationally: a compute-only node surfaces NoStorageCap rather than NotParticipating, even when both gates would reject — the most actionable signal wins.

BlobOverflowController + tick driver

pub struct BlobOverflowController<'a> {
    pub local_caps: &'a CapabilitySet,
    pub capability_index: &'a CapabilityIndex,
    pub heat_registry: &'a Arc<Mutex<BlobHeatRegistry>>,
    pub refcount: &'a BlobRefcountTable,
    pub config: &'a OverflowConfig,
}

The controller's candidates(now, size_for_hash) walks the heat registry in ascending-rate order (coldest first), filters out pinned + non-zero-refcount hashes, and for each remaining candidate selects an overflow-enabled peer with sufficient disk-free + matching scope. Target ranking: highest disk_free_gb wins (greedy spread across peers); ties broken by lowest node_id for determinism.

drive_blob_overflow_tick composes the controller + hysteresis state machine + the OverflowPushSink trait:

pub async fn drive_blob_overflow_tick(
    controller: &BlobOverflowController<'_>,
    sink: &dyn OverflowPushSink,
    observation: OverflowTickObservation<'_>,
    size_for_hash: impl Fn([u8; 32]) -> Option<u64>,
) -> BlobOverflowTickReport;

OverflowTickObservation bundles per-tick state (disk stats, hysteresis atomic, clock). The BlobOverflowTickReport carries every counter the Prometheus emitter needs.

MeshBlobAdapter::drive_overflow_tick(ctx, size_for_hash) is the 2-arg convenience wrapper — composes the controller, threads the adapter's refcount / config / overflow_active, runs the tick, auto-records the report into the adapter's metrics.

Wire protocol — OverflowPush RPC

pub struct OverflowPush {
    pub blob_hash: [u8; 32],
    pub size_bytes: u64,
    pub sender_node_id: u64,
}

pub enum OverflowPushAck {
    Accepted,
    Rejected(OverflowReject),
    OpenChunkFailed,
}

The chunk bytes themselves don't ride this RPC — the nudge tells the receiver to open the chunk channel against its local Redex with replication armed; the existing per-chunk replication runtime pulls the bytes from any holder advertising causal:<hash> (typically the sender). The RPC routes through the existing nRPC machinery under the dataforts.blob.overflow_push service name.

• Sender side: MeshNode::send_overflow_push(target, hash, size) -> Result<OverflowPushAck, BlobError> — encodes the request, dispatches via MeshNode::call, decodes the typed ack.
• Receiver side: MeshNode::serve_overflow_push(adapter) -> ServeHandle registers the OverflowPushHandler under the service name. Each inbound request reads live user_caps_snapshot + the capability index, runs admission, on Admit calls adapter.prefetch(BlobRef::small(...)) to open the chunk channel.
• MeshNodeOverflowPushSink — concrete OverflowPushSink impl wrapping Arc<MeshNode>. Maps non-Accepted acks to typed BlobError::Backend so the controller's push_errors counter bumps uniformly.

OverflowReject carries serde::{Serialize, Deserialize} so the typed reason rides inside OverflowPushAck::Rejected across the wire intact.

Prometheus counter family

The adapter's prometheus_text() body emits the full overflow surface:

dataforts_blob_overflow_pushes_admitted_total{adapter="..."}     <counter>
dataforts_blob_overflow_push_errors_total{adapter="..."}         <counter>
dataforts_blob_overflow_pushed_bytes_total{adapter="..."}        <counter>
dataforts_blob_overflow_rejected_no_target_total{adapter="..."}  <counter>
dataforts_blob_overflow_rejected_total{adapter="...",reason="no_storage_cap"}        <counter>
dataforts_blob_overflow_rejected_total{adapter="...",reason="not_participating"}     <counter>
dataforts_blob_overflow_rejected_total{adapter="...",reason="sender_not_overflowing"} <counter>
dataforts_blob_overflow_rejected_total{adapter="...",reason="unhealthy"}             <counter>
dataforts_blob_overflow_rejected_total{adapter="...",reason="scope_mismatch"}        <counter>
dataforts_blob_overflow_rejected_total{adapter="...",reason="insufficient_disk"}     <counter>
dataforts_blob_overflow_high_water_triggered_total{adapter="..."} <counter>   # false→true edges
dataforts_blob_overflow_low_water_cleared_total{adapter="..."}    <counter>   # true→false edges
dataforts_blob_overflow_active{adapter="..."}                     <gauge 0/1>
dataforts_blob_overflow_disk_ratio{adapter="..."}                 <gauge 0..1>

Sender's push_errors_total bumps on every non-Accepted ack (RPC transport + admission rejection + chunk open failure). The receiver's rejected_total{reason} family bumps on each admission rejection by variant — operators dashboarding both sides see matching volumes.

Hysteresis transitions only bump on the edge: false → true increments high_water_triggered_total, true → false increments low_water_cleared_total. Repeated active-during ticks don't bump either counter, so the metrics count distinct "overflow episodes" rather than steady-state ticks.

net-blob overflow status CLI

net-blob overflow status
net-blob --format json overflow status

Prints the configured boolean, the runtime overflow_active flag (set by the most recent tick on this process), the configured thresholds, and the cumulative counter family. JSON form is shape-stable: top-level keys adapter / config / active / counters, with every per-reason counter present even at zero (operator dashboards don't want missing keys).

Cross-binding surface

MeshBlobAdapter + the overflow surface ship across all four bindings (Rust, Python, Node/TypeScript, Go, C). Every binding takes a MeshBlobAdapter (or MeshBlobAdapterHandle* for C) at construction, exposes the v0.2 CRUD path (store / fetch / exists / prometheus_text), and surfaces the v0.3 overflow control as a paired getter/setter on enabled + active + config. Every binding uses the same OverflowConfig shape — enabled / high_water_ratio / low_water_ratio / max_pushes_per_tick / scope / tick_interval_ms — and accepts a bool form (the simple master-switch case) where the host language allows.

Rust — MeshBlobAdapter::with_overflow(OverflowConfig { .. }) builder, set_overflow_enabled(bool) / set_overflow_config(OverflowConfig) runtime setters, overflow_enabled() / overflow_active() / overflow_config() getters.

Python — MeshBlobAdapter(redex, "id", overflow=...) kwarg accepting bool or dict; set_overflow_enabled / set_overflow_config methods; overflow_enabled / overflow_active / overflow_config properties. Dict path enforces typed errors: unknown keys raise TypeError (typo defense — high_water_ration doesn't silently fail); invalid scope strings raise ValueError.

from net import MeshBlobAdapter, Redex

redex = Redex(persistent_dir="/data/blobs")
adapter = MeshBlobAdapter(
    redex,
    "py-prod",
    overflow={"high_water_ratio": 0.90, "max_pushes_per_tick": 4, "scope": "zone"},
)
adapter.set_overflow_enabled(True)
print(adapter.overflow_active, adapter.overflow_config)

Node / TypeScript — new MeshBlobAdapter(redex, "id", { persistent?, overflow? }); overflow accepts a typed OverflowConfigJs object. setOverflowEnabled / setOverflowConfig runtime methods; overflowEnabled / overflowActive / overflowConfig getters.

import { MeshBlobAdapter, Redex } from '@ai2070/net';

const redex = new Redex({ persistentDir: '/data/blobs' });
const adapter = new MeshBlobAdapter(redex, 'node-prod', {
  persistent: true,
  overflow: {
    enabled: true,
    highWaterRatio: 0.80,
    lowWaterRatio: 0.65,
    maxPushesPerTick: 8,
    scope: 'zone',
    tickIntervalMs: 30_000,
  },
});
adapter.setOverflowEnabled(false);
console.log(adapter.overflowEnabled, adapter.overflowActive, adapter.overflowConfig);

Go — NewMeshBlobAdapter(redex, "id", *MeshBlobAdapterOpts) constructor; Opts.Overflow *OverflowConfig is the typed config. SetOverflowEnabled(bool) / SetOverflowConfig(*OverflowConfig) methods; OverflowEnabled() / OverflowActive() / OverflowConfig() getters return (value, error) per Go convention. Typed sentinels: ErrBlob / ErrBlobClosed / ErrBlobInvalidConfig.

adapter, _ := net.NewMeshBlobAdapter(redex, "go-prod", &net.MeshBlobAdapterOpts{
    Persistent: true,
    Overflow: &net.OverflowConfig{
        Enabled:          true,
        HighWaterRatio:   0.80,
        MaxPushesPerTick: 8,
        Scope:            "zone",
    },
})
defer adapter.Close()
adapter.SetOverflowEnabled(true)

C FFI — opaque MeshBlobAdapterHandle* from net_mesh_blob_adapter_new(redex, "id", persistent, overflow_json); the overflow config arrives as a JSON string at the boundary so the C consumer doesn't have to mirror the typed struct. Eleven new functions: _new / _free / _store / _fetch / _exists / _prometheus_text plus the v0.3 control family (_overflow_enabled / _overflow_active / _overflow_config returning JSON / _set_overflow_enabled / _set_overflow_config).

MeshBlobAdapterHandle* adapter = net_mesh_blob_adapter_new(
    redex,
    "c-prod",
    /* persistent */ 1,
    "{\"enabled\":true,\"high_water_ratio\":0.80,\"scope\":\"zone\"}"
);
net_mesh_blob_adapter_set_overflow_enabled(adapter, 0);
char* cfg_json = net_mesh_blob_adapter_overflow_config(adapter);
// ...consume cfg_json...
net_free_string(cfg_json);
net_mesh_blob_adapter_free(adapter);

The C surface requires building the cdylib with dataforts,netdb,redex-disk; the Go binding wraps these via cgo and the SDK READMEs document the per-binding shape (Rust / Python / TypeScript / Go / C).

Storage layout + safe-delete

Sender doesn't immediately delete the local copy on OverflowPushAck::Accepted — the durability watermark observation (sender polls capability index for receiver's causal:<hash> advertisement) is deferred to a future P6 follow-up. Today the local copy stays until the standard GC sweep collects it under retention + refcount-zero.

This is conservative-by-default: the receiver may have admitted but the chunk-pull could still fail before the bytes land. Operators running into "sender disk doesn't drain fast enough" today can flip gc --disk-pressure (which bypasses the retention floor for refcount-zero hashes) — the explicit watermark gate lands in v0.16+.

Hardening — clippy + arg-bundling

The OverflowTickContext<'a> + OverflowTickObservation<'a> borrow structs bundle the tick-driver args so neither drive_blob_overflow_tick (4 args) nor MeshBlobAdapter::drive_overflow_tick (2 args) trips clippy's too_many_arguments lint. No #[allow(clippy::too_many_arguments)] anywhere in the overflow surface — the bundling earns the clean signatures.

Test coverage

• P1: 17 pure-logic tests (should_accept_overflow_from × 8 reject variants + admit path + ordering, BlobCapability::overflow_enabled round-trip × 2, OverflowConfig adapter surface × 5).
• P2: 20 controller / tick / hysteresis tests (step_overflow_hysteresis × 4 edge cases, BlobOverflowController::candidates × 7 filter paths, tick-driver tests × 6 against an OverflowPushRecorder mock, scope_covers × 2, MeshBlobAdapter::overflow_active shared-state × 1).
• P3: 7 wire-format + integration tests (postcard round-trip × 5 variants + 2-node MeshNode::send/serve_overflow_push end-to-end × 2).
• P4: 10 metrics + CLI tests (record_overflow_tick bumps × 4 paths, per-reason record_overflow_reject × 1, Prometheus body shape × 2, CLI overflow status Human + JSON + metrics-body inclusion × 3).
• P5: 12 Python pytest tests (default-off + bool-true + bool-false + dict-overrides + dict-prestage + scope-parsing + unknown-key + bad-scope + bad-type + runtime-setter + whole-config-setter + round-trip × 12).

Total: 66 new tests across the v0.3 overflow track.

---

Read-your-writes (Phase 5)

Every successful Tasks::create / Memories::insert / etc. returns a WriteToken { origin_hash, seq }. Pass it to wait_for_token(token, deadline) and the call blocks until the local fold has actually applied that sequence number — not just folded it. A producer reads its own write through the cache deterministically; no busy-poll, no time-window heuristic.

WriteToken

pub struct WriteToken {
    pub(crate) version: u8,
    pub(crate) origin_hash: u64,
    pub(crate) seq: u64,
}

Fields are pub(crate); the public constructor is #[doc(hidden)]. FromStr is gated behind #[cfg(test)] or the wire-debug feature. Tokens are unforgeable only against the adapter that issued them (via origin binding); the threat model is documented inline (D-19).

wait_for_token — applied vs. folded

Pre-fix, wait_for_token delegated to wait_for_seq, which returned when the folded watermark passed seq — including events that FoldErrorPolicy silently skipped via RedexError::is_recoverable_decode. A producer whose write hit a skip got Ok(()) and then read state that didn't reflect its write.

v0.15 adds applied_through_seq() (events that actually ran through the fold) alongside the existing folded_through_seq() (events the fold saw). wait_for_token waits on applied, not folded; skipped events are no longer auto-acknowledged (D-17).

FoldStopped error variant

wait_for_seq previously returned Ok when running == false (the fold task crashed under FoldErrorPolicy::Stop). Every pending RYW wait resolved with a silent Ok(()) even though seq was never folded. v0.15 adds WaitForTokenError::FoldStopped { applied_through_seq }; the wait path checks applied_through_seq >= seq when it wakes due to running == false and surfaces the typed error when the fold actually stalled (D-18).

Non-blocking poll — deadline_ms == 0

wait_for_token(token, 0) now does a synchronous applied-vs-token check and returns Ok(()) / Err(Timeout) / Err(FoldStopped) without scheduling a wait. Pre-fix the FFI rewrote 0 to 1 ms, costing a real wait round-trip for a "is fold caught up?" probe (D-23). The synchronous-poll behavior is consistent across the FFI / Node / Go / Python surfaces; the Python surface promoted poll_for_token to the public API alongside wait_for_token so non-async Python callers can probe without spawning a task (N-4).

Process-wide in-flight cap

The 1024-deep wait-queue cap was per-adapter pre-fix; a process with 100 channels could stack 100 K outstanding RYW waiters. v0.15 ships set_global_ryw_inflight_cap(usize) for a process-wide bound; every wait_for_token call does a two-tier acquire (process-wide first, then per-adapter). The semaphore is renamed ryw_inflight_cap with a non-FIFO documentation note (the current implementation is Semaphore::try_acquire; true FIFO is deferred) (D-37, D-38).

Cross-binding API surface

Binding	Surface
Rust	tasks.wait_for_token(token, Duration) / memories.wait_for_token(token, Duration); tasks.poll_for_token(token) synchronous variant
Python	tasks.wait_for_token(token, deadline_ms=…); deadline_ms=0 is a non-blocking poll (N-4)
Node	tasks.waitForToken(token, deadlineMs); deadlineMs === 0 is a non-blocking poll
Go	tasks.WaitForToken(token, timeout) + tasks.PollForToken(token) + tasks.WaitForTokenContext(ctx, token) non-blocking variant; Go context cancellation isn't propagated into the FFI wait — see WaitForTokenContext rustdoc for the contract (D-45, N-11)
C	net_tasks_wait_for_token / net_memories_wait_for_token; timeout_ms == 0 is a non-blocking poll. Every FFI entry wraps block_on in std::panic::catch_unwind(AssertUnwindSafe(…)); panics surface as NET_ERR_PANIC rather than unwinding across extern "C" (D-21)

---

Channel-hash widening — u16 → u32 canonical

The wire NetHeader::channel_hash (16 bits, 65 536 buckets) routinely collides at mesh scale — birthday-paradox threshold ~300 channels. Pre-fix every substrate decision keyed on the wire u16: ACL (AuthGuard), storage (Redex), config (ChannelConfigRegistry), token (PermissionToken), RYW. Two unrelated channels colliding on u16 shared one ACL decision, one RedexFile, one config row.

v0.15 widens the canonical channel hash to u32 substrate-wide while keeping the wire NetHeader::channel_hash at u16 — the per-packet width is fixed by the 64-byte cache-line-aligned header budget. The wire u16 is now a fast-path filter hint only; wire-side collisions are benign because every non-fast-path decision (auth / storage / config / RYW) keys on the canonical 32-bit hash via registry-side disambiguation.

Mirrors the origin_hash u64-canonical / u32-wire precedent set in v0.13: per-packet width fixed, application layer wider, narrowing helper at the wire boundary.

Canonical type

pub type ChannelHash = u32;

impl ChannelName {
    pub fn hash(&self) -> ChannelHash { … }        // canonical u32
    pub fn wire_hash(&self) -> u16 { … }            // wire fast-path hint
}
pub fn channel_hash(name: &str) -> ChannelHash { … }
pub fn wire_channel_hash(name: &str) -> u16 { … }

ChannelHash joint-collision threshold is ~65 K channels per process (above realistic deployment), so the canonical key is treated as collision-free in fast paths.

ChannelConfigRegistry — dual index

pub struct ChannelConfigRegistry {
    configs: DashMap<String, ChannelConfig>,
    by_hash: DashMap<ChannelHash, Vec<String>>,    // canonical (u32, rare collisions)
    by_wire_hash: DashMap<u16, Vec<String>>,       // wire (u16, routine collisions)
    prefix_configs: DashMap<String, ChannelConfig>,
}

get(canonical) returns None on the rare canonical collision (forces caller fallback); get_by_wire_hash(wire) returns None on wire-bucket collision (used by receive-side dispatch, contrast with ChannelRegistry::get_all_by_wire_hash below). Removals stay collision-safe — remove(canonical) keys on the unique canonical hash; remove_by_name(name) is the explicit-name path.

ChannelRegistry — return the full collision set

ChannelRegistry::get_by_wire_hash was renamed to get_all_by_wire_hash and explicitly returns the full collision-bucket vector. This contrasts with ChannelConfigRegistry::get_by_wire_hash, which returns None on collision to force a safe default at the policy layer. The naming asymmetry is intentional — operators querying "what channels share this wire bucket" want the full set; the policy layer querying "what's the config for this packet" wants a unique answer or nothing.

AuthGuard — canonical u32 ACL

The bloom-filter key buffer widens from 10 to 12 bytes (u64 origin_hash + u32 channel_hash); check_fast / authorize / revoke signatures all take ChannelHash. The two-tier authorization shape (fast-path bloom + verified cache + exact-name backstop) is unchanged; the canonical hash makes the fast-path bloom collision-resistant at realistic scale. The exact-name backstop remains the only collision-free path for control-plane / storage authorization decisions where adversarial canonical-hash collisions matter.

PermissionToken — 161-byte wire form

issuer:           32 bytes (EntityId)
subject:          32 bytes (EntityId)
scope:             4 bytes (u32)
channel_hash:      4 bytes (canonical ChannelHash, u32; was u16)
not_before:        8 bytes (u64 unix timestamp)
not_after:         8 bytes (u64 unix timestamp)
delegation_depth:  1 byte  (u8)
nonce:             8 bytes (u64)
--- signed ---
signature:        64 bytes (ed25519)

Total: 161 bytes (was 159). Signed payload: 97 bytes (was 95). PermissionToken::from_bytes rejects 159-byte input as TokenError::InvalidFormat; old tokens must be reissued under the wider form.

RPC inbound dispatcher — (canonical, dispatcher) pairs

MeshNode::register_rpc_inbound(channel_hash: ChannelHash, dispatcher) takes the canonical hash. The dispatcher map is indexed by the wire u16 for O(1) lookup on the inbound packet decode path; each bucket stores a Vec<(ChannelHash, RpcInboundDispatcher)> so wire-bucket collisions between independently-registered canonical channels don't share a dispatcher slot. RpcInboundEvent::channel_hash is the canonical u32 — dispatchers receive the disambiguated identity.

Five post-merge follow-up commits

A focused review pass landed five hardening commits on the channel-hash-32 branch after the primary widening:

#	Commit	Concern	Test added
1	fda25a7d	Race in unregister_rpc_inbound clobbering a concurrent sibling register	sibling-survives + race-stress
2	af5f6c25	Stale "16-bit verified cache" comment in mesh.rs	n/a (doc)
3	1fb62fbc	Stale 16-bit framing in two regression test docstrings	n/a (doc)
4	c141e691	Per-packet Vec allocation in the dispatch fast path	end-to-end wire-bucket collision fan-out
5	c5e75ff6	get_by_wire_hash semantics divergence between registries	full-collision-set contract test

The single-dispatcher hot path (the overwhelming case at typical sizing) avoids the heap allocation entirely; the collision-set vector is built only when a wire bucket has more than one canonical entry. The unregister race is closed by atomic remove-if-present semantics; concurrent register + unregister can no longer leave the map in a torn state.

Dataforts greedy stays on wire u16

The greedy data-plane cache deliberately keys on the wire u16 (not the canonical u32) because the wire hash is what the inbound packet that triggered the observe call carries — there's no canonical lookup at packet decode time. The cache file is named dataforts/greedy/<hex16>; two wire-colliding channels share a cache file (a small mix-up at the data-plane layer; ACL and storage decisions stay collision-safe via the canonical hash).

---

Hardening — dataforts-feature two-pass review

Two coordinated review passes landed before the v0.15 branch cut. The primary review on the dataforts-feature branch surfaced 54 numbered items (D-1..D-54): 4 blockers, 19 highs, 24 mediums, 7 lows. An independent second pass on 2026-05-12 surfaced 11 N-series items (N-1..N-11): 3 highs, 6 mediums, 2 lows. All but three closed before merge (deferred with rationale in the tracking doc). The closures group by area:

Greedy correctness (D-1..D-8 + D-25..D-28 + N-5)

• Cluster-cap eviction withdraws chain announcements inline (D-1).
• Bandwidth-budget rejection bumps a distinct counter rather than dropping events silently (D-2).
• upsert on update subtracts the old bytes before replacing the file pointer (D-3).
• chain_caps resolves the chain publisher's caps via the capability index, not the last-hop peer's (D-5).
• TOCTOU on is_new_channel collapsed into a single locked get-or-insert (D-6).
• tokio::spawn per inbound event bounded by a semaphore (D-7).
• colocation_target_held resolved from the cache map, not hardcoded None (D-8).
• gravity_tick coalesces N×announce_capabilities into one via announce_heat_batch (D-25).
• Retention-trim drift on entry.bytes resyncs via RedexFile::retained_bytes (D-26).
• 5 cache-lock acquisitions per dispatch coalesced to 1 in the steady-state path; new-channel path takes 2 with TOCTOU re-check (D-28).
• Eviction explicitly drops gravity.heat lock before calling sink.withdraw_chain to avoid lock-ordering hazards (N-5).

Gravity correctness (D-9..D-11 + D-29..D-30 + N-2 + N-9)

• origin_hash == 0 no longer collapses per-chain heat (D-9, fix at publish-side + defense-in-depth at gravity-runtime entry).
• HeatRegistry bounded + LRU-evicted + tick-pruned (D-10, N-2).
• Inbound heat: tags gated on the publisher's matching causal: claim (D-11; per-peer rate-limit deferred per N-8).
• should_emit_heat subnormal-safe via is_normal() + EPSILON-floor (D-29, N-9).
• Log-scale wire normalization with configurable reference rate (D-30 / D-46).

Blob correctness (D-12..D-16 + D-31..D-36 + D-49..D-50 + D-52..D-53 + N-3 + N-6 + N-7)

• FileSystemAdapter::store hash-verifies bytes (D-12).
• URI-scheme keyed adapter dispatch closes authority confusion (D-13).
• 4-byte magic for BlobRef discriminator closes payload-misclassification (D-14).
• BlobRef size bounded; fetch_range guards usize cast (D-15).
• Streaming hooks on BlobAdapter (D-16).
• Log injection via BlobError::NotFound(uri) sanitized (D-31).
• Unique-suffix temp filenames (D-32); fsync of temp + parent dir (D-33).
• Per-channel BlobAdapterRegistry override (D-34).
• Bounded concurrency on spawn_blocking (D-35).
• Conformance suite extended with idempotency / hash-mismatch / range-past-end / cross-blob isolation / random-ghost (D-36).
• BlobError marked #[non_exhaustive] (D-49).
• RedexFileConfig::blob_adapter_id unset surfaces the right error variant (D-50).
• OpaqueCtx(AtomicPtr<c_void>) collapsed to plain *mut c_void (D-52).
• Adapter timeout user-tunable (D-53).
• path_for defends against symlinks in the shard root via canonicalize (N-3).
• Windows rename-fallback TOCTOU on idempotent re-store hash-verifies existing content (N-6).
• catch_unwind + caller-held locks documented as a hazard in ffi/mod.rs + per-binding READMEs (N-7).

RYW correctness (D-17..D-19 + D-37..D-38 + D-45 + D-51 + N-4 + N-11)

• wait_for_token waits on applied seq, not folded (D-17).
• FoldStopped error variant when fold task crashes mid-wait (D-18).
• WriteToken doc-hidden constructor + threat-model docstring (D-19).
• ryw_inflight_cap rename + non-FIFO doc note (D-37).
• Process-wide set_global_ryw_inflight_cap with two-tier acquire (D-38).
• Go binding lands Tasks + Memories adapters with WaitForToken + PollForToken + WaitForTokenContext (D-45).
• wait_duration_nanos_sum saturating u128 → u64 cast (D-51).
• Python wait_for_token(deadline_ms=0) non-blocking poll consistent with FFI / Node / Go (N-4).
• Go context cancellation doc contract clarified (N-11).

FFI / cross-binding (D-20..D-23 + D-39..D-44 + D-54 + N-1 + N-10)

• cgo externs link cleanly without dataforts feature via NET_ERR_FEATURE_NOT_BUILT stubs (D-20).
• Panics across FFI caught + remapped to NET_ERR_PANIC (D-21).
• Vtable per-field null-check (D-22).
• timeout_ms == 0 honored as non-blocking poll (D-23).
• mesh_arc drop coverage via RAII guard rather than duplicated drop-on-error (D-39).
• Node await_tsfn_promise applies the 30 s timeout once (was 30 s × 2 → 60 s worst case) (D-40).
• Node DataGravityConfigJs *_secs / _ms widths match the Rust + Python + Go peers (D-41).
• Python Py<PyAny> adapters can no longer outlive interpreter finalization (D-42).
• Python adapter data.to_vec() copies inside py.detach (D-43, N-1).
• Go omitempty doc note on greedy / gravity numeric fields (D-44 deferred — substrate rejects 0 for every affected field; omitempty is correct).
• Go runtime.SetFinalizer runs blocking Close on the GC thread — doc note rather than refactor (D-54).
• Python atexit drain counts drained vs. missing entries via NET_PY_TRACE_ATEXIT env var (N-10).

Hygiene (D-47..D-48)

• metrics.rs channel-cap race doc note (D-47).
• _force_use_hashmap dead allow removed (D-48).

The deferred N-8 (per-peer rate-limiting of heat: tags) is acknowledged in D-11 and tracked for a separate slice; the auth-via-causal-claim gate forecloses the dominant attack vector today.

---

Test hygiene

• Lib suite at 2645+ tests (was 2640+ at v0.14 release). 60+ net new tests across the four Rebel Yell phases + the channel-hash widening; every numbered review item ships with at least one regression where the shape made one possible. Notable additions: greedy admission + eviction unit coverage, gravity heat-counter decay + emission edge cases, blob conformance suite, RYW applied-vs-folded watermark separation, channel-hash canonical-vs-wire collision tests, RPC dispatcher race-stress + sibling-survives.
• Cross-binding wire-format fixtures regenerate against the 161-byte token wire form. The 159-byte token vectors under tests/cross_lang_capability/ rename and re-encode; binding-side tests that hardcoded the 159-byte length update accordingly.
• cargo clippy --all-features --all-targets -D warnings clean across substrate + every binding crate.
• cargo doc --all-features --no-deps clean under RUSTDOCFLAGS="-D warnings" — rustdoc::broken_intra_doc_links and rustdoc::private_intra_doc_links both enforce.
• Go go vet ./... clean under CGO_ENABLED=1; the pre-existing testOrigin uint32 / uint64 mismatch in cortex_test.go is fixed alongside the FFI net_channel_hash u16 → u32 change.

---

Breaking changes

Wire format — PermissionToken is 161 bytes

PermissionToken::WIRE_SIZE grows from 159 → 161 bytes; the signed payload grows from 95 → 97 bytes. PermissionToken::from_bytes rejects 159-byte input as TokenError::InvalidFormat. Old tokens must be reissued; mixed v0.14 / v0.15 fleets cannot exchange tokens. Recommend lockstep upgrade.

Wire format — BlobRef magic widens to 4 bytes

BlobRef::MAGIC = [0xB0, 0xB1, 0xB2, 0xB3]. Pre-v0.15 1-byte-discriminator blob refs (if any pilot deployment serialized them) are rejected on decode. Dataforts is new in v0.15, so this only matters for pre-release pilots.

API — ChannelHash = u32 substrate-wide

• ChannelName::hash() returns u32 (was u16). New ChannelName::wire_hash() -> u16 exposes the wire fast-path hint.
• channel_hash(name: &str) -> u32 (was u16). New wire_channel_hash(name: &str) -> u16.
• AuthGuard::{check_fast, authorize, revoke, is_authorized} take ChannelHash (was u16).
• PermissionToken::channel_hash is u32 (was u16); TokenScope::with_channel, try_issue, TokenCache::{check, get} all widen.
• MeshNode::register_rpc_inbound takes ChannelHash (was u16); RpcInboundEvent::channel_hash is u32.
• ChannelConfigRegistry::{get, remove, priority} take ChannelHash; new get_by_wire_hash(u16) for receive-side disambiguation.
• ChannelRegistry::get_by_wire_hash renamed to get_all_by_wire_hash and explicitly returns the full collision-bucket vector.

FFI — net_channel_hash takes uint32_t*

// v0.14
int net_channel_hash(const char* channel, uint16_t* out_hash);
// v0.15
int net_channel_hash(const char* channel, uint32_t* out_hash);

Go / Python / Node bindings widen their channel_hash / channelHash exports to uint32 / int (u32 range) / number (u32 range). TokenInfo.channel_hash fields widen to match.

API — Dataforts surface is new

Redex::enable_greedy_dataforts(mesh, GreedyConfig, local_caps, IntentRegistry), Redex::disable_greedy_dataforts(), Redex::enable_gravity_for_greedy(mesh, DataGravityPolicy), Redex::disable_gravity_for_greedy(), BlobAdapterRegistry, BlobRef, BlobAdapter trait, WriteToken, tasks.wait_for_token / memories.wait_for_token are all new in v0.15. Behind the dataforts Cargo feature; non-dataforts builds see typed RedexError stubs ("requires the dataforts feature; rebuild with --features dataforts") rather than a silent no-op.

Behavioral fixes that may surface as test breakage

• Greedy dispatch_event is now lock-coalesced. Tests that asserted on the pre-fix 5-lock-per-dispatch behavior will see 1 lock in the steady state, 2 in the new-channel path.
• HeatRegistry is capped at 8 K entries. Tests that fill the registry with > 8 K entries to observe unbounded growth will see LRU eviction.
• should_emit_heat returns Skip on near-zero prev. Tests that injected prev = 1e-300 to observe the pre-fix inf-prone branch will see the bootstrap arm instead.
• wait_for_token returns Err(WaitForTokenError::FoldStopped) when the fold task crashed mid-wait. Tests that asserted Ok(()) against a fold-stopped adapter will see the typed error.
• wait_for_token(token, 0) is a non-blocking poll across every binding. Tests that injected 0 expecting a real 1 ms wait will see the synchronous return.
• PermissionToken::from_bytes rejects 159-byte input. Tests that hardcoded the 159-byte wire form will see TokenError::InvalidFormat.

---

How to upgrade

1. Bump your Cargo.toml / package.json / requirements.txt / go.mod to the v0.15 line. Recompile / rebuild the binding cdylib (NAPI for Node, maturin for Python, cargo build -p net-compute-ffi + -p net-rpc-ffi for Go) with the dataforts Cargo feature on (pre-built release artifacts ship with the feature enabled).
2. Channel-hash type migration. Use ChannelHash (u32) for ACL / storage / config / RYW decisions; use ChannelName::wire_hash() / wire_channel_hash() for the 16-bit header value when constructing wire-level packets. The renames are compile errors — cargo build (and the binding-side TypeScript / Python static checks) drives the rewrite.
3. Token reissue. PermissionToken wire form is 161 bytes. Reissue tokens to clients; pre-v0.15 159-byte tokens are rejected on decode. The signed-payload field shifts mean old signatures don't verify against the new layout — there's no in-place upgrade.
4. Greedy opt-in. Channels that want greedy caching: call Redex::enable_greedy_dataforts(mesh, GreedyConfig, local_caps, IntentRegistry) once after constructing the Redex (idempotent). The runtime registers a GreedyObserver on the mesh's inbound dispatch; admission decisions run per inbound event without any per-channel opt-in. Redex::disable_greedy_dataforts() removes the observer.
5. Gravity opt-in. Layer gravity on top of greedy with Redex::enable_gravity_for_greedy(mesh, DataGravityPolicy). The tick loop spawns automatically; tune decay_half_life_secs, tick_interval_ms, emit_threshold_ratio, normalization_reference_rate to match the deployment's read-rate skew.
6. Blob adapter registration. For channels that publish payloads above the inline threshold: register an adapter (register_filesystem_blob_adapter(id, root) for the in-tree FS adapter; register_blob_adapter(id, instance) for a host-language adapter), then blob_publish(adapter_id, uri, bytes) / blob_resolve(blob_ref) against the registered URI scheme.
7. RYW opt-in. Capture the WriteToken returned from every tasks.create / memories.insert; pass it to tasks.wait_for_token(token, deadline) before reading state that needs to reflect the write. deadline_ms = 0 is a non-blocking poll.
8. Operator dashboards. Redex::greedy_prometheus_text() emits per-channel greedy metrics in Prometheus text format. Heat emissions ride the existing capability-announcement metrics — dataforts_gravity_emit_total, dataforts_gravity_heat_registry_size, etc.
9. Single-binding deployments without dataforts. Builds without the dataforts Cargo feature surface typed RedexError stubs from every enable_* entry point. The substrate substrate path is unchanged — RedEX, CortEX, NetDB, replication all work as in v0.14.
10. Cross-binding wire fixtures regenerated. If you have CI that asserts golden-vector parity against tests/cross_lang_capability/, the 161-byte token form means token-bearing fixtures change. The blob-ref fixtures land for the first time in v0.15.
11. FFI consumers (C / cgo). net_channel_hash takes uint32_t* (was uint16_t*). The four new Dataforts entry points (net_redex_enable_greedy_dataforts, net_redex_disable_greedy_dataforts, net_redex_enable_gravity_for_greedy, net_redex_disable_gravity_for_greedy) follow the existing net_redex_* shape. Without the dataforts feature, the symbols return NET_ERR_FEATURE_NOT_BUILT rather than failing to link.
12. Mixed v0.14 / v0.15 fleets. Replication traffic continues to work cross-version (the SUBPROTOCOL_REDEX wire format is unchanged). Tokens do not (161 vs 159 bytes). Recommend lockstep upgrade for any deployment using PermissionToken-bearing channels.