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]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: da3a0fb7-2fa9-4079-a9a2-cc1c40ee952a

📥 Commits

Reviewing files that changed from the base of the PR and between 432362c and 53b01af.

📒 Files selected for processing (5)

• Cargo.toml
• nucleus/Cargo.toml
• nucleus/README.md
• nucleus/src/heed.rs
• nucleus/src/testkit.rs

🚧 Files skipped from review as they are similar to previous changes (4)

• nucleus/README.md
• nucleus/Cargo.toml
• nucleus/src/testkit.rs
• Cargo.toml

---

📝 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

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The pull request also adds a standalone v42 calculator interface and workspace members not explicitly required by issue #28.	Move the v42 calculator interface and unrelated workspace-member additions to a separate pull request, unless they are required dependencies with documented scope.

✅ 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 directly explains the nucleus crate, its feature-gated primitives, shutdown coordination, and intended engine integration.
Linked Issues check	✅ Passed	The changes implement the linked issue objectives, including shared primitives, feature gates, test support, and ordered shutdown coordination [#28].
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 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