v0.1.1

This is v0.1.1 !!!

What's in here

Here is what v0.1.1 represents as a whole:

Wire Protocol & Versioning

• Explicit protocol_version field in Hello / HelloAck, bumped to 4
• Structured wire errors (WireError): ProtocolMismatch, OpRejected, RateLimited, NotAuthorized, Internal
• New MessageKind::Error variant; protocol mismatch now sends WireError::ProtocolMismatch when possible before closing, instead of dropping the socket silently
• New WireRetryPolicy enum (#[non_exhaustive]) describing per-error reconnect semantics (fatal, retry, retry-after, request-fatal)
• E2E test: previous release binary (v0.1.0) + current binary reject incompatible protocol versions without exchanging ops
• Documented compatibility matrix: same version accepted, mismatches rejected

Reconnect Loop Backoff

• Backoff is now differentiated by error type, not by "any failure"
• WireError::RateLimited { retry_after_ms } honored, bounded by the configured reconnect max delay, without growing exponential backoff
• Fatal wire errors (ProtocolMismatch, NotAuthorized) stop automatic reconnect for that configured peer with a warn! log
• Retryable errors keep the normal exponential backoff
• PeerReconnectState::stop() + guarded loop: a stopped peer is never retried until reset
• Overflow-safe deadline arithmetic: Duration::MAX retry-after no longer panics

Schema & Migration

• Magic number + version header in every sled table: __nx/schema/<table>
• Legacy migration v0 -> v1: validates existing records without rewriting payloads
• Generic step registry for sequential N -> N+1 upgrades
• Structured record migrations are now scoped: a record step may only mutate its own source key in the source namespace (no silent sibling writes or deletes)
• Fixture-based migration test generated from the v0.1.0 tag

Offline Migration CLI

• New command: nx migrate --datastore-path ./nx-data
• Configurable batch limits: --max-records, --max-bytes (default 4MiB, resolved from a single source of truth)
• Missing-datastore case handled as a proper MigrationError::MissingDatastore { path } instead of an ad-hoc CLI bail
• Documented in the CLI reference alongside nx run and nx config

sync_manager Refactor

• Monolithic sync_manager.rs split into sync_manager/ submodules
• OpApplier trait per CRDT family
• E2E tests split per CRDT family under tests/e2e/
• The sync_manager split itself was intended to be behavior-preserving; the later roadmap items in this release (versioning, migration, typed wire errors) did change public API, wire protocol and CLI surface

Crate Versions Pinned

• Every internal crate is now referenced by explicit version = "0.1.1" alongside its path, across the workspace and all examples
• cargo package --workspace --no-verify --offline now passes
• Makes packaging, downstream consumption and any future crates.io release straightforward

Docs

• New design pages: Wire Versioning and Schema Versioning
• New WireError semantics table (retry policy + meaning per variant) in nx-net reference
• Gossip Protocol compatibility table updated for protocol 4 and the new Error frame
• CLI reference updated with nx migrate
• Roadmap updated: the entire v0.1.1 block (Split, Wire Versioning, Schema Versioning, Typed Error Frames) is now closed
• A few crate reference pages still mention the old monolithic sync_manager.rs; they will be cleaned up in a follow-up docs pass

---

What this changes

v0.1.0 was the first stable line for non-critical workloads.

v0.1.1 answers a different question: what happens the day you actually need
to upgrade a running cluster ?

• The wire contract is now explicit: peers on different protocol versions refuse each other with a structured error, not a crash and not silent drift.
• The persistence layer is now explicit: every sled table carries a magic number and a version, and a documented step registry can move it forward one version at a time.
• The reconnect loop is now honest: a fatal wire error stops trying, a rate-limit is honored, a transient error keeps backing off exponentially. No more "everything looks the same when things are actually broken".
• The migration path is now runnable offline: nx migrate can be pointed at a stopped datastore and produce a valid, upgraded one, in bounded batches, without ever starting a node.

The closing criterion for v0.1.1 on the roadmap was:

sync_manager.rs no longer exists as a single file.
A cluster with a 0.1.1 node and a 0.1.0 node refuses the connection with
a clear, versioned error, not with a crash.

Both hold as of this release.

---

Upgrade notes

From v0.1.1-rc.1
Drop-in. Same wire protocol (4), same on-disk schema, same CLI surface.
Only visible source break: WireRetryPolicy is now #[non_exhaustive]; if you
were matching on it exhaustively, add a _ arm.

From v0.1.0
Wire protocol goes 2 -> 4. v0.1.0 and v0.1.1 nodes will not talk to each
other. Upgrade the whole cluster.

On-disk schema is versioned starting from this line. Before starting a
v0.1.1 node on a v0.1.0 datastore:

1. Stop any process using the datastore.
2. Back up the datastore directory.
3. Run:

nx migrate --datastore-path ./your-nx-data

4. Start the v0.1.1 node against the migrated datastore.

The migration is bounded (--max-records, --max-bytes) and resumable.

---

What is next

v0.1.2 - Performance & Profiling.

The roadmap for v0.1.2 is already published: automatic profiling, per-module
CPU/memory metrics, and a regression gate in CI so any PR that worsens sync
p99 latency, throughput or RSS above the configured budget gets blocked
automatically.

---

Thank you !! :)

v0.1.1-rc.1

This is v0.1.1-rc.1, a pre-release. The official v0.1.1 release is still in development.

---

Pre-release for migration testing

This release candidate exists to validate the first datastore migration path from v0.1.0.

If you have a v0.1.0 datastore and want to help test the upgrade path, feedback would be extremely valuable. Please open an issue or leave a comment with the result.

v0.1.1 will be released as stable once the version is complete and hardened.

Current development lives on the v0.1.1 branch. It will be merged into main when the release is ready.

---

What's included

Wire Protocol

• Explicit protocol_version field in Hello / HelloAck bumped to version 3
• Documented compatibility matrix: same version accepted, mismatches rejected
• E2E test: previous release binary (v0.1.0) + current binary reject incompatible protocol versions without exchanging ops

Schema & Migration

• Magic number + version header in every sled table: __nx/schema/<table>
• Legacy migration v0 -> v1: validates existing records without rewriting payloads
• Generic step registry for sequential N -> N+1 upgrades
• Fixture-based migration test generated from the v0.1.0 tag
• New CLI command: nx migrate --datastore-path ./nx-data

sync_manager Refactor

• Monolithic sync_manager.rs split into sync_manager/ submodules
• Added OpApplier trait per CRDT family
• E2E tests split per CRDT family under tests/e2e/
• Refactor intended to preserve behavior while improving structure

Docs

• New design pages: Wire Versioning and Schema Versioning
• Updated Gossip Protocol compatibility table
• Roadmap updated

---

Still in progress

• Typed error frames (WireError enum)
• Remaining v0.1.1 hardening
• Some docs and examples still need final v0.1.1 updates

---

For migration testers

Before testing:

1. Stop any process using the datastore.
2. Back up the datastore directory.
3. Run:

nx migrate --datastore-path ./your-nx-data

Thanks !!

v0.1.0

This is v0.1.0 !!!

---

The journey

Five alphas built the foundation.
One release candidate hardened it.

v0.1.0 is the answer to a question that was asked before a single line of code was written:

but will anyone care about this stuff?

Today, the answer is yes :)
Thanks to all the crazy people who took an interest in numax and found it to be an interesting project!!

---

What's in here

Everything from v0.1.0-rc.1 - which means everything from all five alphas - is included. Here is what v0.1.0 represents as a whole:

Runtime core

• Wasmtime execution engine with strict sandboxing and WASI preview1
• Embedded key/value store (sled) - no external database, no orchestrator
• Module compilation cache - same WASM bytes compiled once per runtime instance

Networking

• TCP networking with mTLS (TLS 1.3), NodeID derived from hash(cert.public_key), peer allowlist
• Automatic reconnect with exponential backoff
• Peer health tracking: suspect -> dead -> healthy
• Periodic anti-entropy (PullSince) to recover missed ops after reconnects
• bincode as the default wire format (~50% smaller, ~10x faster than JSON)
• Protocol version negotiation - mismatches rejected at handshake
• Ping/Pong health protocol - health checking over the wire works

CRDT suite (Phases 4-14, complete)

• GCounter - the proof of concept
• PNCounter - signed convergence
• LWW-Register - last-writer-wins with timestamp ordering
• ORSet - add/remove with unique tags, concurrent add wins
• LWW-Map - field-level last-writer-wins, independent resolution per key
• RGA - Replicated Growable Array with deterministic insert ordering and tombstone support

Host API (nx_sdk)

• nx_sdk::db: get, set, exists, paginated prefix scan
• nx_sdk::crdt: full suite of six CRDTs
• nx_sdk::time: time_now, time_monotonic
• nx_sdk::crypto: random_bytes, hash_sha256, hash_blake3
• nx_sdk::net: net_node_id, net_peers
• nx_sdk::sys: env_get, module_id, abort, host_capabilities, event_emit

Observability

• Structured JSON logging with correlation IDs
• Prometheus-compatible /metrics endpoint with 10 runtime metrics
• /health (liveness) and /ready (readiness) endpoints
• Memory sandboxing enforced - max_memory_bytes wired to wasmtime::StoreLimitsBuilder

Resilience

• Bounded op deduplication persisted across restart
• Durable CRDT state and op-log hydration on startup
• Task Vec cleanup - no unbounded growth in long-running nodes
• Configurable event channel capacity - no hardcoded queue limits

CLI

• nx run with sync, TLS, datastore, and observability flags
• nx run --version
• --print-* flags for all six CRDTs
• Graceful shutdown: drain, close, flush

Documentation

• Complete HOST_API.md
• Full installation guide for Linux, macOS, and Windows
• Cookbook with practical recipes
• CRDT and state documentation
• Runtime model, WASM execution, gossip protocol, local-first philosophy
• Quickstart guide with distributed examples

CI

• Multi-OS: Ubuntu, macOS, Windows
• Load gates: single-node throughput, multi-node full-mesh sync (300s), chaos restarts

---

What this means

v0.1.0 is not a feature list.

It is a runtime that:

• runs untrusted WASM modules in a memory-sandboxed environment
• persists state locally without a central server
• synchronizes that state across peers using mathematically sound convergence
• reconnects automatically when the network fails
• tells you exactly what it is doing through structured logs and live metrics
• exposes a host API that feels like a real host

---

A moment

numax started as a question and a blank Cargo.toml.

Then came a GCounter. Then a TCP socket. Then mTLS. Then sled. Then reconnects. Then bincode. Then an entire CRDT suite. Then a documentation site. Then a documentation site that actually ships.

This is the beginning of numax !
v0.1.0 is a foundation, and foundations are meant to be built upon.

What is next

v0.1.0 ships today.

The roadmap is already open for what comes next.
If you have ideas, open an issue.
If you want to contribute, the door is open.

---

Thank you

If you've been following since alpha.1, you've watched this runtime go from a GCounter and a TCP socket to a complete, documented, load-tested, multi-OS runtime with a full CRDT suite and a host API that actually feels like a host.

To @AndyFerns - the first external contributor, who brought C and C++ into the story.
To @sarvesh1327 - who made --version exist.
To everyone who starred, cloned, read the whitepaper, opened an issue, or just gave the idea a chance.

You are the reason v0.1.0 exists and v0.1.0 is the reason what comes next will be possible !!

I hope this project can make people understand that there is still room for a good software and, as I also say in the whitepaper:

in conclusion, I love software and I love Numax.

GianIac

v0.1.0-rc.1

This is the first release candidate of numax.

Five alphas built the foundation.
rc.1 is where the alpha cycle ends and the hardening begins.

---

What's in here

• Everything from v0.1.0-alpha.5
• Phase 14 - Extended CRDT Suite: PNCounter (increment/decrement, signed convergence), LWW-Register (last-writer-wins with timestamp ordering), ORSet (add/remove with unique tags, concurrent add wins), LWW-Map (field-level last-writer-wins, independent resolution per key), RGA (Replicated Growable Array with deterministic insert ordering and tombstone support)
• Full SDK surface for all five new CRDTs: nx_sdk::crdt::{pncounter, lww_register, orset, lww_map, rga}
• New CLI flags: --print-pncounter, --print-lww-register, --print-lww-map, --print-orset, --print-rga
• New distributed examples: distributed_inventory (PNCounter), distributed_status (LWW-Register), distributed_tags (ORSet), distributed_settings (LWW-Map), distributed_comments (RGA)
• Memory sandboxing enforced: max_memory_bytes now wired to wasmtime::StoreLimitsBuilder — the runtime actually caps guest linear memory per invocation
• Ping/Pong protocol: incoming Ping messages now generate a Pong reply — health checking over the wire works
• Task Vec cleanup: completed async tasks are pruned from the internal task list — no more unbounded growth in long-running nodes
• Redundant peer slot check removed: TOCTOU race in connect_to_peer eliminated, semaphore is the single source of truth
• Module compilation cache: same WASM bytes compiled once per runtime instance, not on every run_module call
• Configurable event channel: NodeConfig::event_channel_capacity propagated to SyncManager — no more hardcoded 100-slot queue
• HOST_API.md updated to cover the full Phase 14 CRDT surface

---

What this changes

alpha.5 answered: what can a guest actually do at runtime?

rc.1 answers the next honest question: is this runtime ready to be trusted?

The CRDT suite is now complete for v0.1.0.
GCounter was the proof of concept. PNCounter, LWW-Register, ORSet, LWW-Map, and RGA are the rest of the story.
Five data structures, each with different convergence semantics, each wired end-to-end from guest WASM to SyncManager to sled to wire.

Alongside the new CRDTs, this release closes every hardening item that was open after alpha.5:
memory limits that actually enforce, a network layer that responds to health checks, a node that doesn't leak memory under sustained peer churn, and a compilation path that doesn't re-pay the wasmtime compile cost on every invocation.

Nothing in rc.1 is experimental. If it's in the list above, it's tested.

---

Why this release exists

Each alpha was one honest step forward.

rc.1 is different.
It's not one new thing. It's the moment where everything that was built across fourteen phases becomes a coherent whole.

The alpha cycle is over.
The focus from here is stability, final API review, and the remaining release criteria tracked in the roadmap.

---

What is next

v0.1.0 is next !

---

A thank you

If you've been following since alpha.1, you've watched a runtime go from a GCounter and a TCP socket to a full CRDT suite, dual-mode serialization, mTLS, Prometheus metrics, load-tested network resilience, and a guest API that actually feels like a host.

The trajectory is real.
And rc.1 is proof that it leads somewhere.

GianIac

v0.1.0-alpha.5

This is the fifth and final technical preview of numax.

alpha.4 made it resilient when the network isn't.
alpha.5 makes the runtime honest about what it can do and gives guests the tools to ask.

This is the last alpha. The next release will be v0.1.0-rc.1.

---

What's in here

• Everything from v0.1.0-alpha.4
• Phase 12 - Extended Host API: key existence check (db_exists), paginated prefix scan (db_scan, db_scan_after, db_keys, db_keys_after, keys_prefix_page_after), time functions (time_now, time_monotonic), crypto primitives (random_bytes, hash_sha256, hash_blake3), system utilities (env_get, module_id, abort), runtime introspection (host_capabilities, event_emit), and network identity (net_node_id, net_peers)
• Phase 13 - Load Testing: single-node store throughput bench, multi-node full-mesh sync bench (300 s), chaos restart bench all with JSON reports under crates/*/reports/load/
• nx run --version flag by @sarvesh1327
• HOST_API.md updated to cover the full Phase 12 surface
• Whitepaper updated with test suite coverage and load testing details

---

What this changes

alpha.4 answered: what happens when the network is unreliable?

alpha.5 answers the next honest question: what can a guest actually do at runtime?

Before this release the host API was mostly db_get, db_set, crdt_gcounter_inc.
A guest had no clock, no randomness, no way to scan its own data, no way to know what runtime it was running on.

All of that changes here.
The full Phase 12 surface is implemented, tested, and documented.
Phase 13 load gates confirm the runtime holds under sustained write pressure, multi-node continuous sync, and chaos restarts.

---

Why this release exists

Each alpha is one honest step forward.
Not a feature dump, a specific thing that was missing and now isn't.

alpha.5 is: WASM modules can now use the runtime as a real host, with time, randomness, prefix scans, crypto, system introspection, and the ability to query what the host exposes.

---

What is next

The alpha cycle ends here.

v0.1.0-rc.1 is next the first release candidate.
The focus shifts from adding surface to hardening what exists: stability, final API review, and the remaining v0.1.0 release criteria tracked in the roadmap.

---

A thank you

@sarvesh1327 contributed the --version flag for the CLI, a small thing that should have been there from the start, and now it is. That's exactly the kind of contribution that makes a project more complete. Thank you.

And thank you to everyone who has starred, shared, cloned, or just read the README.
If you've been following since alpha.1, you've watched a runtime go from a proof of concept to something with a full host API, network resilience, dual-mode serialization, and reproducible load gates.

That trajectory is real. And it's faster !

v0.1.0-rc.1 is already planned!

GianIac

v0.1.0-alpha.4

This is the fourth technical preview of numax.

alpha.3 made the runtime stable enough to trust under load.
alpha.4 makes it resilient when the network isn't.

It is still alpha. It works, it's tested, and it's honest about what's missing.

What's in here

• Everything from v0.1.0-alpha.3
• Automatic reconnect with exponential backoff for configured peers
• Peer health tracking: suspect → dead after N consecutive failures, healthy on reconnect
• Peer rotation: when a peer dies, the next configured peer fills the slot
• Periodic anti-entropy (PullSince) to recover missed ops after reconnects or long disconnections
• Bounded OpId deduplication persisted across restart — no double-count after reboot
• Durable CRDT state/op-log hydration on startup; materialized sled totals retained as fallback
• bincode as the default production wire format (~50% smaller, ~10× faster to parse than JSON)
• JSON wire format still available via --debug-protocol for local inspection
• Format negotiation in Hello/HelloAck; protocol version bumped to 2
• Protocol version mismatch now rejected at handshake, not silently tolerated
• Serialization benchmark: cargo bench -p nx-net
• Minimal C guest example (examples/guest_c) by @AndyFerns
• Minimal C++ guest example (examples/guest_cpp) by @AndyFerns

What this changes

alpha.3 answered: what happens when things get busy?

alpha.4 answers the next honest question: what happens when the network is unreliable?

A node that can't reconnect loses updates permanently.
A node that can reconnect but has no durable state restarts blind.
A node with durable state but a verbose wire format pays the JSON tax on every sync message.

All three problems belong in the same release. Now they're solved together.

Why this release exists

Each alpha is one honest step forward.
Not a feature dump, a specific thing that was missing and now isn't.

alpha.4 is: you can disconnect a node, bring it back, and it converges.
No manual intervention. No data loss. No duplicate counts.

A thank you

This release also marks the first external code contribution to numax.

@AndyFerns added two guest examples, one in C, one in C++ showing that numax isn't just a Rust story.
Both are minimal, well-documented, and immediately runnable.
That kind of contribution is exactly what makes a project more real.
Thank you.

And thank you to everyone who has starred, shared, cloned, or just read the README.
Every signal matters at this stage.

v0.1.0-alpha.5 is already planned !

GianIac

v0.1.0-alpha.3

This is the third technical preview of numax.

alpha.2 made the distributed behavior observable from the CLI.
alpha.3 makes the runtime stable enough to trust under load.

It is still alpha. It works, it's tested, and it's honest about what's missing.

What's in here

• Peer connection limit (default: 64)
• Queued ops limit (default: 10,000)
• Message size limit (default: 16 MiB)
• Socket read/write timeouts (default: 30s)
• Graceful rejection when overloaded
• Test: 1000 simultaneous connections → no crash
• Structured logging (JSON format, configurable levels)
• Correlation ID to trace operations end-to-end
• Prometheus-compatible /metrics endpoint
• /health (liveness) and /ready (readiness) endpoints
• 10 runtime metrics: ops, peers, sync latency, store size, errors and more
• Configurable observability listener (--observability-listen)
• Tests: /ready returns 503 before runtime readiness, unknown paths return 404

What this changes

alpha.2 proved you could run two nodes and watch them converge.

alpha.3 answers the next honest question: what happens when things get busy?

The runtime now has hard limits on connections, queue depth and message size.
It won't silently degrade, it rejects gracefully.
And it now tells you what it's doing: structured logs, live metrics,
health probes that actually reflect runtime state.

That's the foundation you need before trusting a runtime with anything real.

Why this release exists

Each alpha is one honest step forward.
Not a feature dump a specific thing that was missing and now isn't.

alpha.3 is: you can put numax under pressure and see what it does.

A thank you

68 stars. Two forks. People reading the whitepaper and trying the examples.

For a project that's been public for less than a week, that's more signal than I expected.
It means the idea is worth something to someone other than me.
That matters more than the number.

If you've starred, shared, cloned, or just read the README, thank you.
You're the reason alpha.4 exists.

v0.1.0-alpha.4 is already planned !

GianIac

v0.1.0-alpha.2

This is the second technical preview of numax !

The first alpha received more attention than expected, so I decided to move quickly and publish the next piece instead of leaving it sitting on the roadmap.

It is still alpha. It works, it's tested, and it's honest about what's missing.

What's in here

• Everything from v0.1.0-alpha.1
• Robust long-running mode for nx run with sync enabled
• Bounded settle mode for CLI demos and smoke tests
• --wait-before-run, --settle-for, and --print-gcounter
• GCounter hydration from sled at startup
• Signal handling for SIGINT, SIGTERM and SIGHUP
• Graceful shutdown: drain in-flight sync work, close connections, flush the store
• Configurable shutdown timeout, default 30s
• Multi-process CLI smoke test: two real nx run processes converge
• Crash / restart and SIGTERM persistence coverage
• Updated distributed examples: distributed_counter, vote_tally_tls
• Updated roadmap and whitepaper for v0.1.0-alpha.2

What this changes

The first alpha proved the internal sync path:

guest WASM --> SyncManager --> sled

This alpha makes that path visible from real CLI processes.

You can now run separate runtimes with separate datastores, let them exchange CRDT operations over the network, observe convergence, and shut them down cleanly.

That means the examples are now truly distributed, not just local demos with future intent.

Why this release exists

The goal of alpha.2 is simple: make the distributed behavior observable from the CLI.

No hidden service.
No external database.
No orchestrator.

Just two runtimes, two local stores, one CRDT, and convergence.

v0.1.0-alpha.3 is already planned !

Thank you so much to everyone who looked at the first alpha, starred the project, opened the repo, or just gave the idea a chance.

GianIac

v0.1.0-alpha.1

This is the first technical preview of numax !

It is alpha. It works, it's tested, and it's honest about what's missing.

What's in here

• Wasmtime runtime with strict sandboxing + WASI preview1
• Embedded local key/value store (sled)
• GCounter CRDT (commutativity, associativity, idempotency verified by tests)
• TCP networking with length-prefixed JSON protocol
• TLS 1.3 + mTLS, NodeID derived from hash(cert.public_key), peer allowlist
• End-to-end sync wiring: guest WASM → SyncManager → sled, covered by E2E tests
• SDK (nx_sdk::db, nx_sdk::log, nx_sdk::crdt::gcounter)
• CLI (nx run) with sync, TLS and datastore flags
• Multi-OS CI: Ubuntu, macOS, Windows
• Examples: distributed_counter, distributed_chat (local-only), vote_tally_tls

What's not in here yet

Tracked explicitly in ROADMAPmd:

• Long-running lifecycle + graceful shutdown (Phase 7)
• GCounter hydration from sled at startup (Phase 7)
• Backpressure & connection limits (Phase 8)
• Observability structured logs, Prometheus, health (Phase 9)
• Full network resilience, reconnect, anti-entropy, dedup (Phase 10)
• Dual-mode JSON/bincode serialization (Phase 11)
• Extended host API db_scan, time_now, random_bytes, … (Phase 12)
• Load testing (Phase 13)
• Additional CRDTs PNCounter, LWW-Register, ORSet, LWW-Map, RGA (Phase 14)

Install (from source, for now)

git clone https://github.com/GianIac/numax
cd numax
git checkout v0.1.0-alpha.1
cargo build --release

Why this release exists

To get a real signal from real people on whether this idea is worth pushing further.

If numax interests you, the most useful things you can do today:

• run the examples
• try to break the sandbox or the sync
• open an issue, even a small one
• drop a star if you think the idea has legs

GianIac