feat: add nucleus engine crate

[bmuddha]

What changed

Added the nucleus crate with feature-gated primitives shared across the engine stack.

Why

Ledger, runtime, storage, and orchestration crates need common types and lifecycle
coordination without assigning storage or execution policy to the shared dependency.

Closes #28.

Impact

• Introduces shared slot and byte-size types, ledger positions, runtime messages,
  metrics helpers, thread-local runtime state, and test support.
• Keeps Heed, ledger, metrics, runtime, shutdown, testkit, and TLS support behind
  narrow crate features.
• Provides ShutdownManager, service handles, ordered cancellation tiers, and
  bounded termination reporting.

Reviewer notes

Shutdown cancels the replication client, pacemaker, sequencer, and remaining
services in order. Each tier receives its own bounded window to report completion
before shutdown advances.

Follow-up

Ledger, keeper, processor, engine, and replication services consume these
feature-gated primitives upstack.

[bmuddha]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat: protect authoritative accounts from overwrites #37
• feat: add state replicator crate on top of the engine #25
• feat: adds top level engine crate for global orchestration #24
• feat: added internal built-in magic root program #23
• feat: implement transaction processor crate #22
• feat: implements keeper crate - state orchestrator #17
• feat: implement superblock based ledger crate #15
• feat: add optimized accountsdb crate #14
• feat: add nucleus engine crate #18 👈 (View in Graphite)
• feat: add svm crate #21
• feat: add program runtime crate #20
• feat: add transaction context crate #19
• feat: forked transaction-view for increased limits #33
• feat: add customized solana-account crate #13
• chore: import upstream Solana runtime crates #31
• dev

This stack of pull requests is managed by Graphite. Learn more about stacking.

[coderabbitai]

Warning

Review limit reached

@bmuddha, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 20 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 931c605f-ffb0-4e79-be7c-c906825c8a66

📥 Commits

Reviewing files that changed from the base of the PR and between 166f116 and b1463b5.

📒 Files selected for processing (3)

• nucleus/README.md
• nucleus/src/ledger.rs
• nucleus/src/shutdown.rs

📝 Walkthrough

Walkthrough

The workspace adds the feature-gated nucleus crate and the v42-calculator-interface crate. Nucleus provides shared configuration, ledger, runtime, storage, metrics, notification, TLS, shutdown, and test-support APIs. The calculator crate defines RPN instructions and expression builders.

Changes

Engine primitives and calculator interface

Layer / File(s)	Summary
Workspace and crate manifests Cargo.toml, nucleus/Cargo.toml, programs/v42-calculator-interface/Cargo.toml	The workspace adds both crates, shared dependencies, feature flags, optional integrations, and lint configuration.
Nucleus shared contracts nucleus/README.md, nucleus/src/lib.rs, nucleus/src/config.rs, nucleus/src/ledger.rs, nucleus/src/runtime.rs	Nucleus adds shared configuration, ledger, runtime, slot, size, and time APIs with feature-gated modules.
Storage, notification, TLS, and shutdown nucleus/src/heed.rs, nucleus/src/notifier.rs, nucleus/src/tls.rs, nucleus/src/shutdown.rs	Nucleus adds transaction helpers, asynchronous notification, thread-local message state, and ordered service shutdown.
Metrics and execution fixtures nucleus/src/metrics.rs, nucleus/src/testkit.rs	Nucleus adds Prometheus and tracing helpers, deterministic fixtures, transaction signing, and calculator test instructions.
Calculator opcodes and expression builder programs/v42-calculator-interface/README.md, programs/v42-calculator-interface/src/lib.rs, programs/v42-calculator-interface/src/opcodes.rs, programs/v42-calculator-interface/src/builder.rs	The calculator interface adds RPN opcode definitions, transfer encoding, expression composition, arithmetic lowering, and recursive CPI serialization.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant OS
  participant ShutdownManager
  participant ShutdownHandle
  participant Service
  OS->>ShutdownManager: Send shutdown signal
  ShutdownManager->>ShutdownHandle: Cancel service tier
  ShutdownHandle->>Service: Notify cancellation
  Service->>ShutdownManager: Report termination reason
  ShutdownManager->>ShutdownManager: Drain tier with timeout

Loading

Possibly related PRs

• magicblock-labs/magicblock-engine#22: The processor crate implements and consumes the new nucleus runtime, block, shutdown, and metrics APIs.
• magicblock-labs/magicblock-engine#31: The nucleus runtime and testkit use Solana account, transaction-context, program-runtime, and SVM crates introduced there.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The v42-calculator-interface crate and its builder and opcode implementation are not part of issue #28's nucleus scope.	Move the v42-calculator-interface changes to a separate pull request or link an issue that explicitly includes them.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the primary change: adding the nucleus engine crate.
Description check	✅ Passed	The description explains the nucleus crate, its feature-gated primitives, shutdown coordination, and intended engine usage.
Linked Issues check	✅ Passed	The nucleus changes satisfy issue #28 by adding shared primitives, feature-gated support, and ordered shutdown coordination without owning storage or execution policy.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch nucleus

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[bmuddha]

@CodeRabbit review

[coderabbitai]

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@nucleus/src/heed.rs`:
- Around line 27-45: Remove the lifetime-extending transmute calls from
DatabaseIndex::write_txn and DatabaseIndex::read_txn. Bind newly opened
transactions to the borrow of self.env(), or adopt an owner that keeps the Env
alive, while preserving supplied transactions and caller-owned storage without
requiring unsafe lifetime assumptions.

In `@nucleus/src/testkit.rs`:
- Around line 60-66: Update the block function’s hash construction so all bits
of Slot contribute to a deterministic hash, avoiding collisions between slots
that differ beyond the lowest byte. Preserve the existing block fields and
ensure distinct Slot values produce distinct hashes within the supported Slot
range.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: ac2e5c95-96a6-453e-a119-976b7e354a00

📥 Commits

Reviewing files that changed from the base of the PR and between 1f187f7 and 432362c.

📒 Files selected for processing (18)

• Cargo.toml
• nucleus/Cargo.toml
• nucleus/README.md
• nucleus/src/config.rs
• nucleus/src/heed.rs
• nucleus/src/ledger.rs
• nucleus/src/lib.rs
• nucleus/src/metrics.rs
• nucleus/src/notifier.rs
• nucleus/src/runtime.rs
• nucleus/src/shutdown.rs
• nucleus/src/testkit.rs
• nucleus/src/tls.rs
• programs/v42-calculator-interface/Cargo.toml
• programs/v42-calculator-interface/README.md
• programs/v42-calculator-interface/src/builder.rs
• programs/v42-calculator-interface/src/lib.rs
• programs/v42-calculator-interface/src/opcodes.rs