Skip to content

feat: implement multi-Raft cell replication (in progress) - #91

Open
forhappy wants to merge 111 commits into
mainfrom
codex/multi-raft-design
Open

forhappy wants to merge 111 commits into
mainfrom
codex/multi-raft-design

Conversation

@forhappy

@forhappy forhappy commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

Cellar now executes native cell commands on per-cell Raft leaders, replicates committed SQLite/LTX state to serving replicas, and gates S3 acknowledgements on verified recoverable archives. Nodes can lead and follow different groups concurrently. This remains an isolated opt-in mode; the complete MR-01 through MR-17 goal is in progress.

MR-01 through MR-12 are complete at their recorded native boundaries. MR-12 adds committed alarms, signed outbox/inbox delivery, durable receiver receipts, replicated conditional settlement, immutable Blob closure and capability gates. Its executable example replaces a primary and resumes retained disks in another process. Stable receiver definition identities permit self/cyclic declarations while immutable namespaces still require the full compiled manifest.

Validation at source a28babe1904c1287cb4d1877674bd98a87313700: 782 unit/integration cases across 21 binaries, all 88 public Node cases, all 16 native effects cases, all six original MR-12 requirements, four compile-fail SDK doctests, two recovery process runs and all 34 recorded checks pass. Executable/output hashes and failed prototype diagnostics are retained in the full MR-12 evidence. Earlier component evidence keeps its original pins; counts from different sources are not added.

MR-13 now adds Node-owned admission closure, accepted application-work drain, bounded authenticated leadership handoff, joined physical closure and bounded final engine/archive/ambiguity observations. Seven native operations cases cover pressure, pending SQL, archive lag, ambiguity, handoff and parked/bounded group reporting. Library source 67845126e241252ec575f0ea2a5ebe2fd06a37de passes 810 unit/integration cases across 24 binaries, Clippy, both LTX modes and four SDK doctests. The example-only successor 275c45d93da4e73e2180f5b0f2f930613b4fcea5 fixes a busy read-only archive poll and passes build, Clippy and two retained-state process runs. All 34 recorded checks pass with their actual source pins in the partial MR-13 evidence; failed diagnostics remain separately recorded. MR-13 remains IN_PROGRESS.

Remaining priorities are MR-13 production CLI/management parity, full role readiness/resources, safe receipt maintenance and fenced disaster recovery; MR-14 batching and workloads; MR-15 release/failure-history qualification and the 24-hour soak; MR-16 measured density and real 30/100/1,000-node tiers; and MR-17 independent-cluster federation. Existing receipt limits still apply without automatic pruning. Local stores and native fixtures do not qualify physical S3, power loss, failure zones, production capacity, larger physical tiers or federation. Native receiver receipts do not imply generic external exactly-once behavior.

See the implementation plan, business-feature contract, technical design and qualification plan.

@forhappy forhappy changed the title docs: design multi-Raft replication and implementation plan feat: implement multi-Raft cell replication (in progress) Oct 20, 2026
@forhappy
forhappy marked this pull request as draft October 20, 2026 03:41
Publish storage views and sync receipts only after the shared engine
persists a coherent group batch. Quarantine failed engines and retain
filesystem and task ownership through the execution domain.

Adapt directory sync and lock handling without changing Raft consensus
source. Use direct dependency paths so external SDK builds retain the
adapters, and generate the pinned protobuf codec without system protoc.
rustproto.proto comes from the pinned pure generator. Watching a missing
copy forces regeneration and rebuilds on every Cargo invocation.

Keep only the real protocol input; generated codec bytes are unchanged.
Drive RawNodes on one domain-owned worker and batch durable updates.
Keep messages, commit advancement and applied markers behind their exact
sync boundaries; proposal admission remains provisional.

Bind callbacks to worker, replica and entry identity. Gate snapshot
installation, bound queued work and pending reads, and preserve typed
engine failure during shutdown. Seed election randomness through the host.
Bind compiled classes and results to immutable image identity.
Retain unresolved submissions across cancellation and term changes.
Retain submitted producers and private SQL ownership after waiter cancellation. Recheck complete authority and exact committed receipts before output, and join callbacks before releasing node directories.

Add bounded SDK handles, native/Axum counter ingress, multi-group failover coverage and a three-node restart drill. Strong reads and S3 archive gates remain explicitly unsupported pending their work packages.
Pin serving source, exact host commands, failure diagnostics and the executable restart drill. Keep MR-07 in progress pending the complete host-contract audit.
A repeated schema identity did not prove the same command contract set.
Bind sorted required command names/digests into the application root while
keeping query compatibility independent of voting.

Qualify live mode admission and both submitted-partition outcomes through
real TLS TCP cuts. Expose diagnostic watermarks without treating them as
proof, export SDK identity types, and join partially started example owners.

BREAKING CHANGE: command contracts now contribute to class identity.
Experimental roots require a fresh namespace for this marker-1 cutover;
no compatibility reader or in-place conversion is provided.
Require opaque VersionToken values for AtLeast and explicit managed signing/verification keys for RaftCellsServices. Persist public verifier retention across rotation and restart so a configuration cannot silently drop live tokens.

Correlate safe ReadIndex barriers with the original query deadline, retry dropped barriers across checked role changes, and bind served positions to the exact durable image marker. Retain completed response byte permits until the waiter consumes or drops them.

This is partial MR-08. Bounded network replica selection, leader fallback and the remaining read-contract audit are still required; S3 archive/restore and the rest of the 17-package scope remain pending.
Require a separate caller-bound query listener and query peer address so a waiting read cannot occupy the control or LTX connection needed for its barrier. Bind bounded RPC requests and replies to full routing identities, schema, channel, sequence, request tag and payload digest.

Add up to eight explicit member attempts and one optional untried leader fallback under the original consistency and invocation deadline. Cancellation closes the query connection and drops the destination waiter. Forwarding does not require query code on the origin voter; the destination checks compatibility before execution.

This remains partial MR-08. The read audit retains broader RPC faults, active ordinary Context/Storage capture, counter HTTP integration and directory/ingress routing outside group membership. The complete 17-package scope remains open.
Publish configured physical process views once per boot and refresh exact trusted keys from an owned bounded timer. Atomically replace all group/query routes, grants, pools and seed epochs without changing membership revisions. Fence stale observations and future installs; retain old worker charges until join.

Preserve cached quorum routes during discovery failures. A newer self supersession closes admission and joins the host. Add native two-cell port-change restart, directory outage, held-metadata shutdown and self-supersession cases, plus bounded atomic refresh contracts. Automatic membership repair remains open.
@forhappy
forhappy marked this pull request as ready for review October 21, 2026 06:50
The process-revocation wrapper multiplied nested TLS future state during native learner startup and overflowed the ordinary test-thread stack. Box its input before constructing the cancellation guard and return the guard directly from the I/O helper. Keep original deadlines, priority cancellation and physical ownership unchanged.
Keep infrastructure ownership across every host initialization error, including preflight failures with retained handles. Cover execution-domain entry failure at the public Node boundary too. A gated lock-drop regression reproduced early error delivery and now verifies physical join, closed admission and immediate recovery reopening.

Add operation-specific storage lock context. Strengthen quorumless seeding to require expected transport refusal and real peer contact; preserve its no-group/no-claim assertions.
Keep physical metadata permission separate from query and quorum authority.
Bound and join RPCs through cancellation, revocation and process refresh.
Bind sends to committed attempts and authenticated receiver receipts.
Stable receiver definition identities permit cyclic bindings while full
namespace manifests retain voting compatibility checks.

BREAKING CHANGE: configure alarms and delivery with RaftHostOptions::effects
and RaftEffectOptions. Experimental delivery capabilities use a hard cutover.
BREAKING CHANGE: Node shutdown reports include the actual Raft close
result, and one production cell host owns the Node raft directory.
Close reports bind node and engine identity, retained archive obligations
and ambiguous commands. Bounded handoff keeps the original stop deadline.
Native effect endpoint hints are weak to release cyclic class bindings.
Raft can become busy between a status sample and transfer admission.
Map its explicit NotReady refusal to Overloaded so callers retain their
original bounded retry policy. Keep ambiguous transport outcomes distinct.
Require the native lagging-voter test to observe the typed refusal.
Retry only overloaded read-only status observations under their original
deadline. Wait for the prior command's archive before holding the next
S3 response. Keep actual apply, ambiguity and physical-join assertions.
Register accepted requests and selected effect jobs before the shutdown
work snapshot. Refuse poisoned admission while still joining owners.
Report parked durable histories with unknown archive coverage and preserve
control progress under shared request/result pressure.

BREAKING CHANGE: the optional Raft Node report is boxed, and close totals
include parked engine histories with an explicit unknown-archive count.
Settlement can occupy the bounded read-only status slot. Retry only
Overloaded within the original deadline; preserve all archive checks.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant